Your architecture diagrams are lying to you

A new backend engineer is three days into an incident rotation when the payments API starts timing out. She opens the wiki, finds the "Checkout Architecture" diagram, and reads it the way you read a map: as a description of the territory. The diagram shows checkout-svc calling payments-svc directly over gRPC, so she pages the payments team and starts digging into their pods. Forty minutes later someone who has been there two years says, almost in passing, that checkout stopped calling payments directly back in Q4. There is a billing-gateway in front of it now, and the gateway is the thing falling over. The diagram was drawn before the gateway existed. Nobody updated it, because updating it was nobody's job.

That diagram was not malicious. It was just old. And old diagrams are worse than no diagram at all, because a blank wall makes you ask a human and a confident-looking diagram makes you trust it.

A diagram is a snapshot, and the system keeps moving

The problem is structural. A diagram is a photograph of a system taken at one instant. The system, meanwhile, is a living thing that changes every time someone merges a PR, adds a queue, splits a service, or deletes a dependency during a refactor without telling anyone. The moment you export that PNG, the photograph and the subject begin to diverge, and nothing in your workflow couples them back together.

Compare that to code. Code drifts too, but you have machinery that fights the drift. Tests fail when behavior changes. Types break the build when a contract changes. A linter complains. CI goes red. The system has feedback loops that make staleness loud. Diagrams have none of that. A diagram can be wrong for a year and the build stays green, the tests stay passing, and the only signal that anything is off is a confused engineer at 2am who does not yet know enough to distrust the picture.

So the diagram survives on goodwill. It stays accurate exactly as long as some specific person remembers to open the editor, find the right file, redraw the boxes, and re-export. That person changes teams. That person goes on leave. That person decides the Jira ticket for "update the diagram" is lower priority than literally everything else, which it always is. Goodwill is not a process. It is the absence of one, and absence does not scale.

The three ways diagrams fail in practice

Stale diagrams are not all stale in the same way. There are three common shapes, and each rots for its own reason.

The first is the hand-drawn board. Someone runs a design session, fills a whiteboard with boxes and arrows, takes a photo on their phone, and drops it into the wiki. It captured a real conversation, which is its whole value, and it captures it forever, which is its whole problem. A whiteboard photo cannot be edited. To change one arrow you redraw the entire board and take a new photo, so nobody ever does. The artifact freezes the system at the exact moment the team understood it least, right at the start, before the hard parts were built. Six months later it is a fossil of an idea, not a description of a system.

The second is the screenshot in the wiki. This one looks more professional. Someone used a real diagramming tool, made clean boxes, exported a PNG, and pasted it into Confluence or Notion. The trap is that the source file and the published image are now two different artifacts living in two different places. The editable original sits in someone's personal Drive or a .drawio file in a repo nobody remembers. The wiki has only the flattened image. When reality changes, updating it means finding the original, which has been lost, so people either give up or redraw from scratch and create a third version that disagrees with the first two. Now you do not have one stale diagram. You have a small archaeology problem.

The third is the one engineers feel smug about: diagrams as code. You write the architecture in Mermaid or PlantUML or a Structurizr DSL, commit it next to the code, and feel virtuous because it is in version control and diffable. This is genuinely better, and it still rots. You just notice later. Text in a repo is only correct if someone renders it, reads it, and notices when it has drifted from the running system. Most of the time nobody renders it. The .mmd file sits in /docs accumulating merge conflicts that people resolve by accepting whatever, and because it is text that nobody looks at, it can be confidently, precisely wrong with perfect syntax. Being in Git tells you when the file changed. It tells you nothing about whether the file matches production.

The deeper trap with diagrams as code is that the version control gives you a false sense of safety. You think because it is in the repo, it is held to the same standard as the code, but nothing enforces that. There is no test that asserts the diagram's edges match the actual call graph. There is no CI step that fails when a service in the .mmd file was deleted three sprints ago. The file has all the ceremony of code and none of the feedback. So it drifts exactly like the screenshot did, just with a Git history that makes the drift look intentional.

What honest documentation actually requires

If goodwill is the failure, then the fix is to remove the dependence on goodwill. Honest architecture docs need three properties, and most of what teams use today has at most one.

A single source of truth. Not a photo and a source file and a re-drawn copy in someone's slide deck. One artifact that everyone edits and everyone reads, so there is no question about which version is current and no archaeology to find the original. The instant you have two representations of the same system, one of them is wrong and you will not know which. And the diagram is only ever half the picture: it holds the what, the boxes and the arrows, while the why behind them lives somewhere else entirely. That other half is what architecture decision records exist to hold, and it rots the same way when nobody writes it down.

Low edit friction. Updating the diagram has to be cheaper than the cost of it being wrong, or people will rationally choose to leave it wrong. If fixing one arrow means redrawing a board or hunting down a lost file, the friction wins every time. The edit has to be a thirty-second change made by whoever noticed the drift, not a scheduled chore assigned to whoever drew it originally.

A tie to the real system. Almost nothing has this property, and it is the one we would pick if we could only have one. The doc should either update when the system updates, or it should surface the drift loudly when it falls behind. The reason code stays more honest than diagrams is that code has feedback loops. Architecture docs need their own. A diagram that can pull its component list from the actual infrastructure, or flag that a service in the picture no longer exists, has crossed from decoration into instrumentation. Without that tie, you are back to relying on a human to remember, which is where we started.

There is a useful analogy here. The reason a type system is worth its friction is not that it catches every bug. It is that it makes a whole class of mistakes impossible to commit without the build telling you. Architecture docs need the same kind of mechanical conscience. A doc that pulls its component list from the running infrastructure cannot silently claim a service exists after you tear it down, because the source it reads from no longer returns it. That is the difference between a drawing and an instrument. A drawing reflects what someone believed. An instrument reflects what is.

These three are a hierarchy. The single source of truth is table stakes. Low friction is what gets people to actually maintain it. The tie to reality is what keeps it honest when people inevitably forget, and people always inevitably forget. This whole failure pattern is what we call docs rot, and it is the thing any serious answer has to attack at the root.

How ArchDocs approaches the problem

ArchDocs is being built around those three properties rather than around prettier boxes. The diagrams are living documents, edited in place, so there is one artifact to read and change instead of a photo plus a lost source file. Docs can reference other docs, so a shared component is defined once and embedded everywhere it appears, and a change propagates instead of forcing you to update five disconnected pictures by hand. And it can import from your cloud infrastructure, so the picture is grounded in the resources that actually exist rather than in someone's memory of what was deployed last spring. The aim is to close the gap between the diagram and the running system, so drift becomes visible instead of silent. ArchDocs is pre-launch, and this is the intent and the design, not a finished, battle-tested claim. The honest version of this paragraph is that the problem is well understood and the approach is deliberate, and the proof is the work, not adoption numbers we do not have.

The test for any diagram

Here is the question to ask of every architecture diagram you rely on. If the system changed last week, would this picture know? For a whiteboard photo, a wiki screenshot, or an unrendered Mermaid file, the answer is no, and the diagram is lying to you whether or not it has noticed yet. The engineer paging the wrong team at 2am trusted an artifact your process promised would be true, then let go stale. Fix the process, not the engineer. And if you need to justify that work to someone holding the budget, the lie is not free: the real cost of stale documentation shows up in onboarding, incidents, and audits long before anyone files a ticket for it.