Infrastructure as code changed how teams manage infrastructure. The core insight: the desired state of your system should be a file in source control, not a series of manual steps or a mental model held by whoever set it up. Terraform, Pulumi, and CloudFormation are the tooling expression of that insight.
The same insight applies to architecture documentation, and most teams haven’t applied it yet. Their architecture diagrams live in Confluence, Miro, or Lucidchart — outside the repository, outside version control, outside the PR review process, and outside CI. They drift. They become wrong. They stay wrong because fixing them is optional. That drift is the root of why architecture diagrams go stale — not careless engineers, but a structural separation between code and documentation.
What Architecture as Code Actually Means
Architecture as code is not a specific tool or format. It’s a practice: defining your service topology in a structured, machine-readable format that lives in source control and drives automatic visualization.
A minimal YAML service definition looks like this:
services:
- name: payments-service
team: platform
stack: [Go, PostgreSQL]
status: active
depends_on:
- fraud-detection
- notification-service
- name: fraud-detection
team: risk
stack: [Python, Redis]
status: active
depends_on:
- ml-inference
This is readable by humans, parseable by tools, diffable in PRs, and lintable in CI. It’s also the input for a visualization layer that generates an interactive dependency graph automatically.
Why Git Is the Right Place for Architecture Documentation
Git gives you four things that no wiki or diagram tool can match:
- Version history — You can see what the architecture looked like 6 months ago. Every change is attributed to a commit and a person.
- PR review process — Architecture changes require a PR. The team reviews them. This is where you catch “wait, should this new dependency go through the API gateway?” before it’s in production.
- CI validation — You can lint the YAML schema, check for circular dependencies, or validate that every service has an owner. These checks run on every PR.
- Colocation with code — The service definition lives in the service’s repository. The engineer changing the code can update the documentation in the same commit.
The Deployment Pattern: Static Visualization from YAML
The visualization layer reads your YAML and generates a static HTML/JS application — an interactive dependency graph deployable on any static hosting provider. No backend, no database, no runtime to manage. The architecture documentation is as stable and cheap to host as a landing page.
On every deploy, the graph reflects the current state of the YAML. Change the YAML, push, deploy: the diagram updates. No manual diagram editing, no drift, no “I’ll update the docs later” that never happens. For the practical mechanics of mapping service dependencies — runtime discovery vs. explicit declaration, building your first map, and the hover-trace pattern — that guide covers the full picture.
Service Map is built on this pattern: define services in YAML, deploy the static visualization on your own infrastructure, get an always-current interactive dependency map. The entire architecture documentation workflow is a 1 YAML file → 1 live graph pipeline.
Related guides: Why architecture diagrams go stale · Mapping service dependencies
