Keeping architecture diagrams current.
Every architecture diagram is accurate on the day it is drawn. The question is what happens in month four.
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
Questions
Can this run in CI?
The desktop app is interactive, so the honest answer is that regeneration is a person running a command. Committing the exported SVG means the diff shows when the architecture changed, which is most of the benefit.
Will the diagram change every time even if the code did not?
Layout is deterministic for a given graph, so an unchanged architecture produces an unchanged diagram. That is what makes a diff meaningful rather than noise.
What about the intended architecture?
Keep that as a separate, hand-maintained diagram. Conflating the target state with the current state is how both become useless.
Related
- Open Source MaintainersMost first-time contributors give up before opening a pull request, and a surprising share of that is not knowing where anything is.
- Consultants and AgenciesYou are handed a codebase, given a fortnight, and expected to explain it back. Uploading it to a SaaS tool is usually not an option.
- Onboarding Engineers to a CodebaseThe first week is spent building a mental model that somebody already has. A diagram transfers it in an afternoon.
- Documenting Legacy CodeIncluding the newest kind of legacy code: what a coding agent wrote for you over several sessions that nobody has looked at as a whole.
Last updated