If you work at a company running more than a handful of services, you already know the problem. Someone joins the team and asks “which services does the checkout flow depend on?” Nobody has a current answer. The architecture diagram on the wiki was accurate in 2022. The tech lead gives a verbal walkthrough from memory, probably missing two things. Two weeks later, the new engineer makes a change that breaks a service nobody mentioned.
This is not a people problem. It is a tooling problem. Architecture documentation rots the moment it is written because it lives outside the codebase. The services keep evolving; the diagram does not.
Service Map solves this by making the source of truth a set of YAML files that live in your repository alongside your code. From those files, it generates an interactive, filterable, always-current dependency graph that any engineer can open in a browser, explore, and share with a link. No backend required. No SaaS subscription. No data ever leaving your infrastructure.
What Service Map Does
Service Map is a self-hosted visualization tool that reads YAML service definitions and renders them as an interactive graph. Each node in the graph is a service. Edges represent dependencies. The graph is live — filter it, focus on a subset, hover over a node to trace its entire upstream and downstream chain, and copy a shareable URL that encodes everything about the current view.
The output is a static web application: HTML, CSS, and JavaScript files that you deploy to any static host. GitHub Pages, Netlify, Vercel, an S3 bucket behind CloudFront, your internal nginx — it does not matter. If it can serve files, it can host Service Map. Zero ongoing infrastructure cost.
You define services in YAML. The format is straightforward:
id: payment-service
name: Payment Service
area: Payments
kind: api
status: active
tech: [Node.js, PostgreSQL]
owner: payments-team
depends_on:
- target: user-service
- target: fraud-detection
- target: stripe
kind: externalThat is the entire definition for a service. Add one file per service to the data/services/ directory, run the build, and deploy. The graph updates to include the new service and its declared dependencies.
The Four Features That Make It Useful Day-to-Day
Filter and Focus Mode
A dependency graph with 40 services is noise if you only care about the payment domain. The filter sidebar lets you narrow the view by product area, service status, technology stack, and team ownership simultaneously. Non-matching services dim out but stay in the layout, giving you spatial context.
When you need to go further, Focus Mode re-runs the layout with only the matching services. Isolated nodes — services with no edges to anything in the filtered set — are excluded. What remains is a clean subgraph of exactly the services relevant to your current question.
Hover Tracing
Hover over any node and Service Map highlights the complete connected chain: every service that feeds into it (upstream) and every service it feeds into (downstream), following the graph in both directions through multiple hops. Everything outside that chain dims. This is the feature that makes impact analysis fast. “If I change the user service, what else is affected?” Hover over it and you have the answer in under a second.
Shareable URLs
Every state of the map — which filters are active, which service is selected, what the search query is — is encoded in the URL. Share a link in Slack and your colleague opens exactly the same view you are looking at. No screenshots, no “let me walk you through how to get there.” Paste the URL. Done.
Automatic Layout
You do not position nodes manually. The layout engine (ELK — Eclipse Layout Kernel) calculates positions automatically using a layered algorithm that respects dependency direction. Services that depend on nothing sit at one end; services that everything depends on sit at the other. The result is a readable graph without any manual arrangement work.
Who It Is For
Service Map is built for engineering teams. The specific personas that get the most value from it are slightly different, so it is worth addressing each one directly.
Engineers Onboarding to a New Codebase
The first week on a new team is spent building a mental model of the system. Service Map compresses that process. Instead of reading READMEs and asking questions to reconstruct the dependency graph in your head, you open the map and have it in front of you. Filter to your team’s area. Hover over the services you have been assigned to. See what they depend on. See what depends on them. The spatial representation sticks in a way that text descriptions do not.
Engineers Planning a Change
Before touching a service, you want to know the blast radius. Hover tracing shows you every downstream consumer that might be affected by a change to the service you are about to modify. This is especially valuable for shared infrastructure services — databases, auth services, internal SDKs — where the dependency graph is deep and not obvious from the code alone.
Architects and Tech Leads
Architecture documentation that is maintained as Confluence pages or draw.io diagrams drifts from reality within weeks. When the YAML files are treated as code and reviewed in pull requests, the map stays current automatically. Architects can use the live graph as a stakeholder communication tool — share a URL instead of a screenshot, and stakeholders see the actual current state rather than a snapshot that may already be outdated.
Engineering Managers and Staff Engineers
Service ownership tracking becomes trivial when every service has an owner field in its YAML. Filter by team to see everything a given team is responsible for. Use the status field (active, deprecated, planned) to track migrations in progress — filter to deprecated services and see what still depends on them, giving you a clear picture of remaining migration work.
The Self-Hosted Advantage
Most architecture visualization tools are SaaS. They charge per seat, require your service data to live on their servers, and add another vendor relationship to manage. When a team of 20 engineers needs access to the map, that is 20 seats at whatever the per-seat rate is. The tools that are good enough to be useful are typically not cheap.
Service Map is a one-time purchase at 99 EUR. You get the full source code. You deploy it yourself. Your service data stays in your infrastructure — it never leaves. There is no per-seat model because the deployment is a static site: anyone with the URL can view it, anyone with repository access can edit it. One license, unlimited internal use.
The self-hosted model also means you control the update cadence. You get one year of updates via git pull. After that, you keep the version you have and it keeps working. There is no “your plan has been discontinued” or “this feature is now Enterprise-only.”
Deployment in Practice
Getting Service Map running takes under 15 minutes for a team that already has Node.js and pnpm installed.
- Clone or download the repository into your project.
- Add your service YAML files to
data/services/, one file per service. - Run the build:
pnpm install && pnpm build - Deploy the
dist/directory to your static host of choice.
For teams using GitHub, the natural home is GitHub Pages with a GitHub Actions workflow that rebuilds and deploys the map on every push to the main branch. Any change to a service YAML file triggers a new deployment, keeping the live map continuously current.
# .github/workflows/deploy-service-map.yml
name: Deploy Service Map
on:
push:
branches: [main]
paths: ['data/**']
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v3
- run: pnpm install
- run: pnpm build
- uses: actions/deploy-pages@v4
with:
folder: distWith this setup, updating the map is as simple as editing a YAML file and merging a pull request. The map updates automatically a few minutes later.
Modeling Your Architecture in YAML
The YAML schema is intentionally minimal. Here is what a complete service definition looks like:
id: order-service
name: Order Service
area: Commerce
kind: api
status: active
tech: [Go, PostgreSQL, Redis]
owner: commerce-team
description: Manages order lifecycle from placement through fulfillment
depends_on:
- target: user-service
- target: inventory-service
- target: notification-service
- target: stripe
kind: externalThe key fields and what they control:
| Field | Purpose | Filter behavior |
|---|---|---|
id | Unique identifier, used as edge target in depends_on | — |
area | Product domain or team area | Filter sidebar Area filter |
kind | Service type: api, worker, database, external, etc. | Filter sidebar Kind filter |
status | Lifecycle state: active, deprecated, planned | Filter sidebar Status filter |
tech | Technology stack (array) | Filter sidebar Tech filter |
owner | Team or individual responsible | — |
depends_on | List of service IDs this service calls | Drives graph edges |
External services — third-party APIs, managed databases, payment processors — are defined in a separate data/externals.yml file and rendered with a distinct visual style. They appear in hover traces but are clearly differentiated from internal services.
Real-World Use Cases
Incident Response
When a service is degraded or down, the first question is always “what else is broken because of this?” Open the map, hover over the affected service, and you see every downstream consumer immediately. Share the URL in the incident channel so the entire response team is looking at the same graph without anyone having to explain the dependency structure verbally.
Deprecation Planning
Mark a service as deprecated in its YAML. Filter the map to deprecated services. The graph shows you every service still depending on the deprecated one. That list is your migration checklist. As teams migrate their dependencies, they update their own service YAMLs. The map shows migration progress in real time.
Tech Stack Audits
Filter by a specific technology — say, a legacy framework you are moving away from. Every service using that framework appears. Filter further by team to assign migration ownership. The map becomes a living audit document rather than a spreadsheet someone updates quarterly.
New Engineer Onboarding
Add a link to the Service Map to your onboarding documentation. New engineers can self-serve answers to structural questions rather than interrupting senior engineers. “How does the notification system work?” — filter to the notifications area and trace the graph. Most questions answer themselves within two minutes of exploration.
Architecture Reviews
Proposing a new service or a significant refactor? Add the new service to the YAML in a branch, build locally, and share a link showing the proposed architecture. Reviewers see the concrete graph rather than reading a written description. Edge cases (circular dependencies, unexpected coupling) are visible immediately in graph form.
How It Compares to Alternatives
| Service Map | Backstage | SaaS diagram tools | Wiki diagrams | |
|---|---|---|---|---|
| Setup time | Under 15 min | Days to weeks | Minutes | Minutes |
| Stays current | Yes (YAML in repo) | Yes (catalog) | No (manual) | No (manual) |
| Self-hosted | Yes | Yes | No | Depends |
| Data leaves org | No | No | Yes | Depends |
| Per-seat cost | No | No | Typically yes | No |
| One-time cost | 99 EUR | Free (OSS) | Subscription | Included in wiki |
| Hover tracing | Yes | No | Varies | No |
| Shareable URLs | Yes | Yes | Varies | No |
| Focus mode | Yes | No | Varies | No |
Backstage is the obvious comparison since it also uses a YAML-based service catalog. The difference is operational overhead. Backstage requires running a Node.js backend, a PostgreSQL database, and managing authentication. For teams that need a full internal developer portal, Backstage is the right tool. For teams that specifically need dependency visualization and nothing else, deploying and maintaining a full Backstage instance is a significant investment for a narrow use case. Service Map does one thing and deploys in 15 minutes.
What Is Included
- Full TypeScript source code — built with Vite, React, ReactFlow, and ELK. Readable, typed, and straightforward to extend.
- Pre-built static files — deploy immediately without running the build yourself if you prefer.
- Sample service data — a realistic set of example service definitions to understand the format and test filters before adding your own data.
- Documentation — covers the YAML schema, all configuration options, deployment instructions for common hosts, and how to extend the tool.
- One year of updates — pull from the repository to receive new features and fixes for 12 months after purchase.
- Unlimited internal use — one license covers your entire organization. No per-seat counting, no additional licenses for new team members.
Technical Requirements
- Build: Node.js 20 or later, pnpm
- Deployment: Any static file host — GitHub Pages, Netlify, Vercel, S3, Cloudflare Pages, or any web server capable of serving static files
- Browser support: Chrome, Firefox, Safari, Edge (all current versions)
- No runtime server required — the built output is entirely static
Frequently Asked Questions
How many services can it handle?
The layout engine performs well up to a few hundred nodes. For organizations with very large service counts (500+), the focus mode and filtering become essential — the full graph will render, but navigation is most practical when filtered to a meaningful subset.
Can I customize the visual appearance?
Yes. Design tokens for area colors, edge colors, status badge colors, and kind icons are centralized in src/graph/styles.ts. Adding a new area or service kind requires updating that file and the schema enum. The source is TypeScript — if you can read it, you can change it.
Does it support teams with multiple repositories?
Service Map is a single deployment with a single data/ directory. The natural pattern for multi-repo teams is a dedicated “service catalog” repository that aggregates YAML files from across the organization. Teams open pull requests to the catalog repo when they add or change services. This is the same model Backstage uses for its software catalog.
What happens after the one year of updates expires?
The version you have keeps working indefinitely. You own the source code. Nothing stops working after 12 months — you simply stop receiving new features and fixes unless you renew or purchase a new license.
Is authentication built in?
Service Map itself has no authentication layer — it is a static site. Access control is handled at the hosting level. For internal-only access, deploy behind your VPN, an internal Cloudflare Access rule, or basic auth at the CDN/web server level. For teams comfortable with public documentation, deploy openly like any other public site.
Can I add custom fields to the YAML schema?
Yes. The schema is defined in src/schema.ts using Zod. Adding a new field is a matter of extending the schema object and updating whatever UI component should display it. The source is structured to make this straightforward for a TypeScript developer.
Does it work with Kubernetes or service mesh tooling?
Service Map is infrastructure-agnostic. It reads YAML files you write — it does not auto-discover services from a Kubernetes cluster or a service mesh. This is a deliberate design choice: auto-discovery captures what currently exists in production, but not the intended architecture, ownership, or lifecycle state. The YAML files are documentation that engineers maintain intentionally.
What is the refund policy?
Standard 14-day refund policy. If it does not work for your use case, contact support within 14 days of purchase for a full refund.
Architecture drift is one of those problems that every engineering team has and most teams tolerate rather than fix, because the available solutions are either too heavyweight (Backstage) or too passive (wiki diagrams). Service Map sits in the gap: lightweight enough to deploy in an afternoon, powerful enough to make dependency questions answerable in seconds, and cheap enough that the cost-benefit calculation is not a difficult one.
At 99 EUR one-time for unlimited internal use, the tool pays for itself the first time it prevents a production incident caused by an undocumented dependency.
