Diagrams as code and keeping documentation current

What diagrams as code means

Diagrams as code means writing a diagram as a short text file in a small language and letting a tool lay it out and draw it. Instead of dragging boxes on a canvas, you write ordering -> db: SQL, and the tool produces the picture. The text file lives in the code repository and is treated like code: versioned, reviewed, checked by automated builds and published by the pipeline.

It is one part of docs-as-code, the practice, championed by the Write the Docs community, of producing documentation with the same tools and workflow as software: issue trackers, version control (usually Git), plain-text markup such as Markdown or AsciiDoc, code review and automated tests. The previous sections produced the material: views and C4 diagrams, UML where precision matters, ADRs and an arc42 structure. This section is about keeping that material accurate for the life of the system, which is where most architecture documentation fails. The reasons it fails were set out in why and how much to document: stale wikis, big documents nobody owns and diagrams that no longer match the system.

Why put diagrams in text

Version control. A diagram in text has a history. You can see who changed it, when and why, and compare any two versions line by line; a binary image or a file in a drawing tool's format shows only that something changed. You can also branch it: the diagram for a proposed change lives on the same branch as the code that implements it.

Review in pull requests. When a developer adds a new dependency between services, the change to the diagram appears in the same pull request as the code, as a readable text diff. Reviewers can ask whether the new arrow is wanted, which is an architecture review at the moment it is cheapest.

Consistency. The tool applies the same shapes, fonts and layout rules to every diagram, so diagrams drawn by twenty people still look like one set. With a modelling language (below), the same element appears with the same name and description in every view.

Generation. Text can be produced by programs. Diagrams can be generated from the code itself (dependency graphs), from infrastructure-as-code (deployment diagrams), from API specifications or from a central model, and then checked automatically against the system.

The trade-offs are real. Automatic layout is convenient but sometimes ugly, and fighting a layout engine to place one box can take longer than drawing it; most tools offer hints such as direction or grouping, not exact positions. Text languages have a learning curve for people who do not code, such as product managers. And a beautiful sketch on a whiteboard during a design discussion is still the fastest way to think; diagrams as code are for the diagrams you intend to keep.

Four languages, one example

Four languages dominate. Each example below describes part of the same food-delivery platform.

PlantUML, created by Arnaud Roques and first released in 2009, is the oldest of the four. It covers all the common UML diagrams (sequence, component, deployment, state, activity, class) and many others, and uses Graphviz to lay out most diagram types. The C4-PlantUML library adds C4 shapes. Its sequence diagrams are particularly good, which makes it a natural choice for the runtime scenarios of UML essentials.

@startuml
title Place an order (happy path)
actor Customer
participant "Customer app" as App
participant "Ordering service" as Ord
participant "Payment provider" as Pay
queue "Order events topic" as MB

Customer -> App : Tap "Pay"
App -> Ord : POST /orders (HTTPS)
Ord -> Pay : Authorise payment
Pay --> Ord : Authorised
Ord ->> MB : OrderPlaced (async)
Ord --> App : 201 Created
@enduml

Mermaid, created by Knut Sveidqvist in 2014, is written in JavaScript and renders in the browser. Its biggest advantage is reach: GitHub has rendered Mermaid blocks in Markdown files since February 2022, and GitLab and many wiki and note-taking tools do the same, so a diagram in a README needs no build step at all. It supports flowcharts, sequence, class, state and entity-relationship diagrams, among others, and has experimental C4 support. Its layout control is limited for large diagrams.

flowchart LR
    app["Customer app<br/>Kotlin, Swift"]
    gw["API gateway"]
    ord["Ordering service<br/>Java"]
    db[("Order database<br/>PostgreSQL")]
    topic[["Order events<br/>Kafka topic"]]
    disp["Dispatch service<br/>Go"]
    notif["Notification service<br/>Node.js"]

    app -->|HTTPS/JSON| gw
    gw -->|HTTPS/JSON| ord
    ord -->|SQL| db
    ord -->|publishes OrderPlaced| topic
    disp -->|consumes| topic
    notif -->|consumes| topic

Structurizr DSL, created by Simon Brown alongside the C4 model, is different in kind. It does not describe a diagram; it describes a model (people, software systems, containers, components and the relationships between them) and then defines views of that model. Each element is defined once, with its name, description and technology, and appears in every view that includes it. Relationships between containers are automatically implied at the system level, so the context view needs no separate arrows. The DSL can also attach Markdown documentation and a folder of ADRs to the workspace, and the tooling can export views to PlantUML, Mermaid, D2 and other formats.

workspace "Food delivery" {
    model {
        customer = person "Customer" "Orders food from local restaurants."
        payments = softwareSystem "Payment provider" "Takes card payments." "External"
        platform = softwareSystem "Food-delivery platform" {
            app = container "Customer app" "Ordering and tracking." "Kotlin, Swift"
            gateway = container "API gateway" "Authenticates and routes requests." "Managed API gateway"
            ordering = container "Ordering service" "Accepts and tracks orders." "Java"
            db = container "Order database" "Orders and their states." "PostgreSQL" "Database"
            orderEvents = container "Order events" "Order lifecycle events." "Kafka topic" "Topic"
            dispatch = container "Dispatch service" "Assigns couriers." "Go"
        }
        customer -> app "Places and tracks orders using"
        app -> gateway "Makes API calls to" "JSON/HTTPS"
        gateway -> ordering "Routes requests to" "JSON/HTTPS"
        ordering -> db "Reads from and writes to" "SQL/TCP"
        ordering -> payments "Takes card payments using" "JSON/HTTPS"
        ordering -> orderEvents "Publishes order events to" "Kafka"
        dispatch -> orderEvents "Consumes order events from" "Kafka"
    }
    views {
        systemContext platform "Context" {
            include *
            autoLayout lr
        }
        container platform "Containers" {
            include *
            autoLayout lr
        }
        styles {
            element "Database" {
                shape cylinder
            }
            element "Topic" {
                shape pipe
            }
        }
    }
}

D2 (Declarative Diagramming), open-sourced by Terrastruct in 2022, is the newest. It aims at clean, modern output and readable syntax, supports nested containers (written with braces and referred to with dotted names), and offers a choice of layout engines: dagre and ELK are bundled and free, and TALA, designed for software architecture diagrams, is a separate commercial engine.

direction: right

customer: Customer {shape: person}
payments: Payment provider

platform: Food-delivery platform {
  app: Customer app
  ordering: Ordering service
  db: Order database {shape: cylinder}
  events: Order events topic {shape: queue}
  dispatch: Dispatch service

  app -> ordering: Places order (HTTPS)
  ordering -> db: SQL
  ordering -> events: Publishes OrderPlaced
  dispatch -> events: Consumes OrderPlaced
}

customer -> platform.app: Places orders using
platform.ordering -> payments: Authorise (HTTPS)

Drawing tools and modelling tools

The difference between Structurizr and the other three is an instance of the distinction between drawing and modelling tools introduced in Section 4.3. A drawing tool (diagrams.net, Excalidraw, Visio, an online whiteboard, and also PlantUML, Mermaid and D2) knows about shapes, lines and text. A box labelled Ordering service in one diagram has no connection to the box with the same label in another. Rename the service and you must find and fix every diagram by hand; misspell it once and you have, as far as the tool knows, two services.

A modelling tool (Structurizr, Archi for ArchiMate models, Sparx Enterprise Architect for UML and SysML, Capella) keeps a model: a repository of elements and relationships with properties. Diagrams are views onto the model. Rename an element and every view changes. The model can be queried (which containers depend on the broker?), checked (no component in the customer app may call the database) and compared with the running system. The price is more up-front structure and, with the heavyweight commercial tools, licences, training and a tendency to model far more than anyone reads.

A practical rule: use drawing tools, text or graphical, for sketches, one-off explanations and diagrams that stand alone, such as a single sequence diagram in an ADR. Use a model when the same elements appear in many diagrams, when several teams contribute, or when you want to check the documentation against the code. Many teams combine them: a Structurizr model for the C4 structure and PlantUML or Mermaid for a few sequence and state diagrams.

Generating documentation in the pipeline

Once documentation is text in the repository, the continuous integration pipeline from Chapter 0 can build and check it like code. A typical pipeline renders every diagram (failing the build on a syntax error), checks links, builds a static documentation site with a generator such as MkDocs, Antora or Docusaurus, and publishes it when changes reach the main branch. Readers then always see the documentation that matches the code on main, and nobody needs to remember to export a picture and upload it to a wiki.

Further checks can be added as the team matures: a spell checker and prose linter (Vale is popular), a check that every ADR has a valid status, a warning when a page's last reviewed date is older than its review interval, and architecture checks that compare the documented dependencies with the actual ones in the code, which are a form of fitness function. Some teams generate parts of the documentation from the system itself: dependency graphs from the build, API reference from OpenAPI specifications, deployment diagrams from infrastructure-as-code.

name: architecture-docs
on:
  pull_request:
    paths: ["docs/**"]
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # assumes plantuml, d2, lychee and mkdocs are available on the runner
      - name: Render diagrams (fails on syntax errors)
        run: |
          plantuml -tsvg docs/diagrams/*.puml
          for f in docs/diagrams/*.d2; do d2 "$f" "${f%.d2}.svg"; done
      - name: Check links
        run: lychee --offline docs/
      - name: Build site (warnings such as broken links fail the build)
        run: mkdocs build --strict
      - name: Publish
        if: github.ref == 'refs/heads/main'
        run: ./scripts/publish-docs.sh

Keeping documentation current

Tools do not keep documentation true; habits do. Five habits make the difference.

Ownership. Every document has a named owner, normally the team that owns the code it describes. In GitHub and GitLab a CODEOWNERS file can make that team a required reviewer for changes under its docs/ folder. Documents owned by everyone are maintained by no one.

Review with code changes. A pull request template that asks Does this change an interface, a dependency, a deployment or a decision? If so, which document or ADR did you update? catches most drift at the moment it happens. Some teams go further and block merges of features that lack documentation, a practice the Write the Docs guide mentions.

Last-reviewed dates. A small header on each page records its owner, the date it was last checked against reality and how often it should be reviewed. Readers can judge how far to trust it, and the pipeline can flag pages that are overdue. A page that says last reviewed 2023 is honest; a page that silently describes the system of 2023 is a trap.

Linking documentation and code. Pages point to the code they describe (paths, modules), code comments point to ADRs, and commit messages cite the records they implement. Links in both directions make it obvious which documents a change might affect.

Deleting stale material. Wrong documentation is worse than none, because readers act on it. When a page no longer describes the system and nobody will fix it, delete it or move it to a clearly marked archive. ADRs are the exception: they are records of history, so they are superseded or deprecated, not deleted. This is the living documentation idea that Cyrille Martraire developed in his 2019 book of that name: documentation that evolves at the same pace as the system, ideally because much of it is derived from the system.

---
title: "Ordering service: building block view (level 2)"
owner: "@ordering-team"
last_reviewed: 2026-09-14
review_every: 6 months
code: src/ordering/
decisions: [ADR-0007, ADR-0012]
---