Diagrams as Code: Treating Architecture Documentation Like Source Code

In 2011 the phrase "Infrastructure as Code" began to shift how operations teams thought about servers. The idea was simple: if you describe your infrastructure in code, you gain version control, auditability, repeatability, and the ability to review changes before they go live. Terraform, Pulumi, and CloudFormation became the standard. Nobody argues for hand-configured servers anymore.

Architecture diagrams are fifteen years behind. Most teams still manage them as binary artefacts — PowerPoint files, Lucidchart exports, Miro boards — stored outside their delivery workflow, reviewed (if at all) out-of-band, and never diffed. The architectural equivalent of ClickOps.

Diagrams as Code applies the same philosophy to architecture documentation. The result is not just cleaner tooling — it changes what architectural governance is possible.

What "Diagrams as Code" Actually Means

A diagram-as-code is a text file that a rendering engine converts to a visual diagram. The two dominant formats are:

• Mermaid — JavaScript-based, natively rendered by GitHub and GitLab in Markdown files. Supports flowcharts, sequence diagrams, class diagrams, ER diagrams, C4 models, and more. Zero installation for teams already using GitHub.
• D2 — Go-based, purpose-built for technical diagrams with first-class support for layout engines (TALA, ELK, Dagre), themes, and structured data. Better default aesthetics than Mermaid; more complex syntax.

Both are plain text. Both are diffable. Both can be committed to git. Both can be rendered in CI pipelines. This is the foundation.

The Git-Native Workflow

The correct workflow for a diagram-as-code system mirrors the workflow for source code:

# 1. Engineer creates a feature branch
git checkout -b feature/payment-retry-queue

# 2. Code changes + architecture diagram update in the same commit
git add src/services/payment/retry-worker.ts
git add docs/architecture/payment-service.md  # contains Mermaid diagram
git commit -m "Add async retry queue for failed payments

Updated container diagram to show new Kafka consumer.
Refs: ADR-042"

# 3. PR review includes diagram diff
# GitHub renders the updated Mermaid diagram in the PR description

# 4. Architecture reviewer approves both code and diagram
# 5. Merge and deploy

The critical step is that the diagram lives in the same repository as the code it describes. Not in Confluence. Not in a shared Google Drive. In the repo, next to the service, in a docs/architecture/ directory.

What You Gain: Five Engineering Benefits

1. Architectural change requests become reviewable

When a diagram is a text file in a PR, anyone on the team can comment on specific lines. "Why are we adding a direct database connection from the API gateway?" becomes a concrete PR comment on the line that draws that arrow — not a vague concern raised in a meeting that may or may not be addressed.

2. History and blame

git log docs/architecture/checkout-service.md shows you exactly when every architectural decision was made, who made it, and what PR it was linked to. This is the architectural paper trail that post-mortems are built on.

3. CI validation

Mermaid diagrams can be validated in CI — a linting step that catches syntax errors before they reach main. D2 diagrams can be rendered to SVG in CI and published as build artefacts, ensuring the rendered output is always current.

4. Search and discovery

Text-based diagrams are searchable. git grep "PaymentService" finds every diagram that references the payment service. When you rename a service, you can find and update all references across all diagrams with a standard search-and-replace — something that is impossible with binary diagram formats.

5. AI augmentation

AI models can read and generate text. They cannot meaningfully process a Visio file. When your diagrams are text, AI can generate first drafts from plain-English descriptions, suggest improvements based on architectural patterns, explain unfamiliar diagrams to new engineers, and detect inconsistencies between a diagram and related ADRs. Text-based diagrams unlock an entire category of AI-assisted architectural tooling that binary formats cannot support.

Practical Transition: A Four-Week Plan

Moving an organisation from binary diagrams to diagrams-as-code does not require a migration project. It requires a practice.

• Week 1: Add a docs/architecture/ directory to your most actively developed repository. Use AI generation to produce a Mermaid C4 context diagram for the service. Commit it. Done.
• Week 2: Add a note to your PR template: "Does this change affect the architecture diagram?" One checkbox, no enforcement. Behaviour starts to shift.
• Week 3: Add a Mermaid lint step to CI. This is a two-line GitHub Actions addition. Any PR that introduces a broken diagram fails the build.
• Week 4: Hold a thirty-minute architecture review using the diagrams in the repo — not a shared Confluence page. The repo is the source of truth.

By month two, the practice is established. By month six, engineers on newly joined teams will not understand why architecture diagrams would ever live anywhere else. That is the goal.

The Tooling Imperative

The barrier to adoption is not philosophical — most engineers agree that diagrams-as-code is the right approach once they have seen it work. The barrier is tooling friction. Writing Mermaid syntax by hand from scratch is slower than opening Miro. Until that friction disappears, adoption stalls.

AI generation removes the friction. Describe the architecture change in a sentence. Get a syntactically correct, contextually appropriate diagram in three seconds. Review it. Commit it. The practice becomes self-reinforcing because the tooling makes it easier than the alternative.

Infrastructure as Code took a decade to become standard practice. Diagrams as Code — with AI generation as the accelerant — will take considerably less time.