Diagrams as Code

A platform group keeps 60 diagrams in a drawing tool. Asked which are still true, nobody can say. The deploy that added a service last week changed no picture, because changing a picture meant opening a different application, exporting an image and attaching it somewhere.

That friction is the whole story. A diagram's accuracy is decided by how many steps stand between noticing the drift and fixing it. Diagrams as code removes the steps: the model is text, it lives beside the code, and the pull request that adds a deployable adds the three lines that put it on the picture.

Why it matters

Stale diagrams are worse than missing ones, because readers plan against them. A new engineer builds a mental model from a container view that lost a service two quarters ago. The failure is silent — no tool reports that a diagram is wrong.

Text changes that. A reviewer sees + container "Export Worker" in a diff rather than two near-identical PNGs, which is the only form in which a diagram can be reviewed rather than admired. One text model also drives several views, so an element named once appears at both context and container level, which removes the commonest contradiction between two pictures of one system.

Implementation patterns

• Start at the context level, one file per system with external dependencies. It changes a few times a year, so it stays true, and it is roughly an afternoon of work per system.
• One model, many views. A reference implementation of the C4 model such as Structurizr keeps a single model and renders several views from it; Mermaid and PlantUML take one file per diagram, which is simpler and reuses nothing.
• Render where review happens. A text diagram that renders only in a separate tool rots exactly as the drawings did. Markdown previews in editors and code-review surfaces now cover this directly.
• Generate the inventory, author the views. Discovery gives what exists, never intent or planned state. Alert when a deployable appears in discovery and not in the model.
• One line in the review template: a pull request that adds or removes a deployable updates the model. This costs about 10 minutes per structural change and is what keeps the practice alive.

Industry example

Text-diagram rendering moved into mainstream developer tooling from 2022: major code-hosting platforms began rendering Mermaid inside Markdown files and pull-request comments in February 2022, and JetBrains' Markdown support renders PlantUML in the IDE preview with Mermaid alongside it. The significance is not the notation — it is that diagrams became visible where engineers already look, which is the condition under which a model is maintained at all.

Failure scenarios

• Auto-layout defeat. A 40-node graph laid out automatically is unreadable and the team goes back to drawing. Split the view rather than fighting the layout engine.
• A second codebase nobody owns. A 3,000-line DSL model with no owner drifts like any unowned code.
• Generated-only diagrams, which drop the intent the pictures existed to carry; the loss stays invisible until someone asks why a component exists.
• Rendering in a tool nobody opens, which reproduces the original problem with extra ceremony.

Trade-offs

When not to use it

For a stable system nobody is changing, the drawings are fine and conversion has no payoff. For the single picture whose job is to persuade — an annotated sketch for a funding decision — a drawing tool wins, because persuasion needs layout the generator will not give you. Below roughly ten deployables, hand-drawn diagrams stay true long enough that the pipeline costs more than the drift.

Interview question

Q: Your group has 60 hand-drawn diagrams and wants a text model in version control, with no pause in delivery. What is your first step and what is the point of no return?

What a strong answer covers: start with the context level for the few systems with external dependencies, because it is small, useful immediately and reversible by deleting files; make it render in the review surface before adding content; add the container level only for systems under active change; put the update rule in the review template. The point of no return is deleting the drawing-tool originals — keep those read-only for a quarter and delete per diagram, never as a batch. A strong answer refuses the big-bang port, because a third of the 60 describe components that churn every few sprints.

Quick check

Quiz: What most determines whether a diagrams-as-code practice survives its first quarter? — That the diagram renders where review already happens; otherwise the model rots like the drawings it replaced.

Flashcard: What does diagrams-as-code buy that a drawing tool cannot, and what does it cost? — Reviewable diffs and reuse of one model across views, in exchange for layout control and a DSL to learn.