Keeping architecture diagrams current.

Why diagrams rot

Not because people do not care, but because updating a hand-drawn diagram costs an hour and updating the code costs the sprint. When the artifact and the system are maintained separately, and one of them is checked by tests and the other is not, only one of them stays true. Nothing about discipline changes that arithmetic.

Generate rather than maintain

If the diagram is derived from the code, refreshing it is a command instead of an hour, and the arithmetic changes. This is the same reason generated API documentation is current and hand-written API documentation is not; the mechanism is unremarkable and it works.

Where to put it

An exported SVG committed to the repository beside the README, regenerated when the architecture changes. Not in a wiki, where it will be found by nobody and updated by no one. In the repository it is beside the thing it describes and it shows up in diffs, which is the closest thing to a review this artifact will ever get.

The honest limitation

Regenerating is cheap, and cheap is not automatic. Something still has to trigger it, and in practice that is a person or a scheduled job rather than a guarantee. This makes staying current realistic rather than solved, which is a meaningful improvement and not the same as a solution.

Refresh

Related

• Onboarding Engineers to a Codebase
  The first week is spent building a mental model that somebody already has. A diagram transfers it in an afternoon.
• Documenting Legacy Code
  Including the newest kind of legacy code: what a coding agent wrote for you over several sessions that nobody has looked at as a whole.
• Architecture Review
  Most of the effort in an architecture review goes into producing the diagrams, and most of those diagrams describe the system as remembered rather than as built.
• System Design Interview Preparation
  The diagram is the easy part. Interviews are decided by the tradeoffs you can defend when the interviewer pushes.