Are architecture diagrams worth maintaining: yes when regeneration is cheap, and here is the break-even

The skeptic's argument deserves its full weight, because it is right about the failure mode. The code is the truth; a diagram is a cache of it, and caches go stale. A wrong diagram is worse than none, since it misleads with the visual authority of something that looks maintained. And every diagram-hours estimate competes against features, so the diagram loses every sprint until it is three architectures behind.

The argument is also right about scope: for a small flow, five services, one queue, the reader is often better served by a Mermaid block living in the same commit as the prose, rendered natively by GitHub in fenced code blocks, updated in the same diff. Below roughly 20 nodes, Mermaid in-commit is a genuinely good answer and maintaining a separate diagram is overhead; the boundary is mapped in docs-as-code diagram limits. Where the skeptic overreaches is treating the maintenance cost as a constant of nature. It is a variable, and it recently changed.

Put numbers on both sides. The value side is reads times minutes saved: a container diagram that spares a reader 5 minutes of code spelunking, read twice a week, returns about 9 hours a year. The cost side is updates times minutes per update, and this is where the two maintenance modes split.

Keep a diagram while:
  reads/yr x minutes saved per read  >  updates/yr x minutes per update

Hand-maintained container diagram:
  cost:   12 updates/yr x 45 min            = 9.0 h/yr
  value:  2 reads/wk x 5 min x 52           = 8.7 h/yr   -> marginal, loses
                                                            as churn rises

Same diagram, regenerated from the repo:
  cost:   12 updates/yr x 5 min review      = 1.0 h/yr
  value:  1 read/wk x 5 min x 52            = 4.3 h/yr   -> clears the bar
                                                            on one read a week

The 45-minute update is where hand-maintained diagrams die: at that price, updates get batched, batching means the diagram is usually wrong, and a usually-wrong diagram loses its readers, which zeroes the value side too. The spiral is economic, not moral.

Regeneration attacks the cost term directly. An AI agent connected to the Datadef MCP server reads the repository and updates the diagram to match, invoked as one command after a merge or in a scheduled CI job. The honest mechanics: Datadef does not watch the repo and nothing fires automatically, the update is agent- or CI-invoked, and the API key it needs comes with paid plans. At 5 minutes of review instead of 45 of redrawing, the break-even drops to a level almost any read pattern clears, and when to regenerate an architecture diagram covers choosing the moments.

Cheap regeneration also fixes the quiet second cost, copy divergence: pages embed one live image URL instead of hosting pasted exports, so an update propagates within minutes to every page showing it, provided the project is shared public, which is a real trade-off for confidential architectures.

Some diagrams fail the inequality no matter how cheap updates get, because the value side is zero. Candidates: diagrams of deprecated systems, detail-level views of components that churn weekly and are better read from code, duplicate views nobody chose between, and any diagram with no reads in two quarters, which embed analytics or wiki page views will tell you.

Delete deliberately: archive the source, replace the page with a one-line tombstone pointing at the living alternative, and note the date. A deliberately dead diagram costs nothing; an accidentally dead one keeps collecting readers and misleading each of them. Deciding this diagram is not worth maintaining is a legitimate output of the arithmetic, and making the decision explicit is what separates pruning from rot.

Keep few diagrams, at the altitudes readers actually use: a context view for orientation and a container view per major system cover most teams. Generate what can be generated, hand-maintain only the small flows where Mermaid-in-commit is cheaper, and delete the rest on purpose. A team running that portfolio spends an hour or two a month on diagrams and gets views it can trust, which is the combination the skeptic correctly said was impossible under manual maintenance.

Priced against the cost of outdated documentation, the trade is lopsided: onboarding and incident navigation lean on architecture views more than on any other doc type.

• Docs-as-code diagram limits
• When to regenerate an architecture diagram
• Cost of outdated documentation
• Best tools to keep docs in sync