ADRs vs architecture diagrams: they answer different questions and decay differently

An ADR captures a decision at a moment: the context that existed, the options considered, the option chosen, and the consequences accepted. Its value comes entirely from being frozen. Six months later, when someone asks why not Kafka, the answer is only useful if it reflects what was known then rather than what is convenient now. This is why the convention is to supersede an ADR with a new one rather than edit it.

A diagram describes the current state. Its value comes entirely from being current. An architecture diagram that reflects a state the system left eight months ago is not a historical record, it is a wrong answer with a confident layout, and it is trusted by exactly the people with the least context to catch it.

So the storage model differs. ADRs are numbered markdown files in the repository, written once, never regenerated, cheap to keep forever. Diagrams should be derived from something that already changes when the system changes, because anything requiring a human to remember will eventually not be remembered.

An ADR library cannot tell you what runs today. After three years you have forty records, six of them superseded, two contradicting each other in ways nobody noticed, and a newcomer would have to replay the entire history to reconstruct the present. That is a reasonable price for keeping the reasoning, and it is not a substitute for a picture.

A diagram cannot tell you why. It shows a queue between two services and gives no hint that the team considered direct calls, measured them, and chose the queue for a specific reason that still holds. Without that, the next team re-litigates the decision, usually by reversing it and rediscovering the reason the hard way.

Neither one covers process, ownership or on-call, which is a third category that belongs elsewhere. See documentation ownership models for that part.

Use the same names in both. If the ADR says the ingest worker, the diagram should have a node called ingest worker, not Worker Service (v2). Shared vocabulary is what lets a reader move between the two documents without a translation step, and it is free.

Reference the ADR number from the diagram, not the other way around. A note on a node saying ADR-014 points at a file whose number never changes. A reference in the ADR pointing at a diagram region will rot when the diagram is redrawn, and editing the ADR to fix it breaks the immutability that makes ADRs worth having.

Treat the diagram as the acceptance test for the ADR. A decision is accepted, the implementing change lands, and the next regeneration either shows the new shape or it does not. If it does not, either the work is incomplete or the decision quietly did not happen. That check costs nothing when the diagram comes from repository sync, because the redraw happens on its own from the connected branch.

docs/adr/
  0001-record-architecture-decisions.md
  0012-use-a-queue-between-api-and-loader.md   Accepted 2026-03-04
  0014-move-schema-validation-to-the-edge.md   Accepted 2026-06-18
  0009-direct-calls-between-services.md        Superseded by 0012

Diagram node note:  "validation at the edge, see ADR-0014"
Never the reverse:  an ADR that points at a diagram region rots on redraw.

This only works if the node the ADR points at survives a redraw. Most generators assign identity per run, so the node that was called Loader last month is a different node this month and every annotation attached to it is orphaned. Nothing outlives the regeneration, and the reference in the ADR was never worth writing.

In a Terraform repository, Datadef derives node ids from the resource address rather than from generation order. The provider prefix is dropped, the module path is kept, and the resource name is appended only when it says something: this, main, default and existing are treated as noise and left out. So module.storage with an azurerm_storage_account named this becomes node-storage-storage-account, and it is that id on every future sync as long as the address is unchanged.

That stability is what turns the reference into a durable one. Rename the Terraform resource and the id changes, which is correct, because the thing the record described has been renamed and someone should notice. Add a consumer and every existing node keeps its id, so the delta reads as one new box rather than a new drawing. On a re-sync the previous diagram ids, labels and zones, up to sixty of them, are handed back to the model as the composition it must keep.

Budget writing time for ADRs and zero maintenance time. Write one when a decision would be expensive to reverse, when it crosses team boundaries, or when you can predict the same argument recurring in a year. Anything smaller is a comment in the pull request.

Budget zero writing time for the inventory diagram and some review time. Connect the repository read only, pick a branch or a tag, and let the daily sync redraw. What you spend time on is deciding whether the picture that came back is the architecture you intended, which is a far better use of an hour than moving boxes.

Keep hand-drawn diagrams for proposals. A picture of the architecture you want, attached to the ADR that proposes it, is genuinely useful and is expected to be superseded. That is the one place where a hand-drawn diagram and an ADR share a lifetime, and it is why the editor matters as much as the sync does.

• Keep ADRs up to date
• ARCHITECTURE.md: the codebase map
• Documentation ownership models
• Repo to diagram: repository sync
• The diagram editor