Mermaid diagram drift: diagrams as code still need a human to type the change

Version control. The diagram now lives on a branch, moves with a tag, and can be reverted. That was the biggest practical problem with a drawing tool export and it is genuinely solved.

Reviewability. A change to the graph appears in the pull request as text a reviewer can read. Compared to a binary image where the diff is unreadable, this is a large win, and it is why teams who adopt mermaid do see fewer wrong diagrams for a while.

Proximity. The diagram is in the same repository as the thing it describes, so the effort of updating it drops from open another tool to edit a file you already have open. Lower effort means more updates, which is real.

None of that is accuracy. Being reviewable makes drift visible to a reviewer who happens to notice. It does not make drift impossible, and it does not tell anyone that a diagram was supposed to change.

Silent omission. Someone adds a call from the orders service to a new pricing service. Nothing fails, no test is red, no reviewer thinks about the README, and the graph now describes a system with one fewer edge than reality. This is the most common and the most damaging, because the diagram looks complete.

Rename skew. A module is renamed in code, every import updated by the tooling, and the mermaid node keeps the old label because no refactoring tool touches a markdown fence. Six months later two names are in circulation and new joiners assume they are two different things.

Layout collapse. Mermaid lays out automatically, and automatic layout degrades as the node count rises. The tangle is not the real problem; the real problem is that maintaining something unreadable feels pointless, so the file keeps growing for a few months out of habit and then freezes. Completeness is what causes this, and it is a trap for generated diagrams too: an early completeness pass of Datadef Terraform pipeline drew 62 resources from a 123-resource repository and produced a column that was correct, complete and unreadable.

A fourth, less discussed: the copy in Confluence. Mermaid renders in GitHub, so the wiki gets a pasted screenshot, and the screenshot is a separate artefact with a separate decay rate. See embed diagrams in markdown for the version of this that does not fork.

<!-- README.md, committed 2025-11, still there today -->
graph TD
  api --> orders
  orders --> ordersdb
  orders --> events

<!-- Since then, in code and not in the graph:
     orders now calls pricing before writing
     ordersdb was split into orders and inventory
     events gained a second consumer
     nothing failed, so nobody noticed -->

The useful split is not mermaid versus a drawing tool, it is inventory versus intent. Inventory diagrams answer what exists and how it is wired, they change every sprint, and they should be generated. Intent diagrams answer what we are planning, how this one flow works, or what the boundary should be, they change when thinking changes, and they should be authored by a person.

Keep mermaid for intent. A sequence diagram for a single feature, a proposal attached to an ADR, a state machine that genuinely does not change: all of these are good uses of a hand-written text diagram, and none of them decay in the way an inventory diagram does. Being wrong is even acceptable for a proposal, because it is dated and superseded.

Generate the inventory, and make the generator curate. Connect the repository read only through repository sync, choose a branch or a tag, and the diagram is redrawn daily. For Terraform repositories every .tf file is parsed with no state and no cloud credentials, modules become zones, and the curation is deterministic rather than left to the model: a resource classified as glue, meaning a role assignment, a grant, a random password or anything from the random, null, local, time, tls, archive or template providers, is never a box and is counted in a summary instead. Repeated minor types inside a module collapse into one node carrying the count and the member names, and a module is allowed eight drawn nodes before its tail collapses into a named supporting-resources node, sixteen when that one module is effectively the whole repository. Nothing is lost: the counts ride on the canvas and the full inventory is the Module reference table in the generated architecture doc.

Then the README block becomes one line. Instead of eighty lines of graph declaration that a human owns, the markdown holds a live embed URL rendering the current canvas, readable without an account, and the maintenance burden goes to zero.

Put the diagram file next to the code it describes rather than all diagrams in one docs directory. A reviewer touching internal/orders is far more likely to notice internal/orders/README.md than a file three levels away.

Add a CODEOWNERS entry so the team that owns the code is requested on changes to the diagram, and so a change to the code without a change to the diagram is at least visible to the same people.

Cap the scope of each diagram deliberately. Three diagrams of ten nodes each stay maintained far longer than one diagram of thirty, because each one has an obvious owner and stays legible. See the limits of docs as code for diagrams.

• The limits of docs as code for diagrams
• Embed diagrams in markdown
• Embed diagrams in a GitHub README
• Repo to diagram: repository sync
• Live embeds: one line of markdown