Architecture Diagrams That Don't Rot: A Living Docs Workflow

Every engineering org has one: the architecture diagram in the wiki that was accurate for a few weeks, years ago. New hires study it, then learn from a colleague that half the boxes were renamed and the queue in the middle was replaced last spring. Most architecture documentation best practices focus on what to draw. This post is about the harder part: keeping diagrams true after the first draft, with a workflow that treats them as living docs instead of one-off artifacts.

Why architecture docs go stale

Diagrams rarely rot because people are lazy. They rot because the process around them makes rot the default.

• They are one-off artifacts. A diagram gets drawn for a design review, a migration kickoff or an audit. Once that meeting is over, nobody has a reason to open it again.
• Screenshots get pasted everywhere. The source file lives on someone's laptop, and a PNG ends up in the wiki, the onboarding doc, three slide decks and a README. Now there are five copies, and none of them can be edited.
• No one owns them. "The platform team" is not an owner. When nobody specific is responsible, everyone assumes someone else will update it.
• Nothing triggers an update. Code changes go through pull requests, review and CI. Diagrams change only when someone remembers, which is rarely the moment the system changes.
• They show too much. A diagram with every Pod, every queue, every IAM role and every user journey is out of date the day it is finished, because any change anywhere makes it wrong.

None of these are tooling problems first; a better drawing tool will not fix a missing owner. But the tool can make the right workflow cheap or expensive.

Architecture documentation best practices for living diagrams

Here is the workflow we recommend. It is opinionated on purpose.

1. One source of truth per diagram

Each diagram exists in exactly one editable place. Everything else is a link or an embed pointing at that place. If you are about to export a PNG to paste somewhere, ask whether a link would do. Usually it will.

2. Link, don't copy

Wikis, docs sites and READMEs should point at the live diagram, not contain a picture of it. An embedded live diagram changes when the source changes; a pasted screenshot is wrong forever after the next change. When you do need a static image, such as a PDF for an auditor, treat it as a dated export and keep it out of the docs people rely on day to day.

3. Name an owner

Every diagram gets an owner: a person, or a team with a named point of contact. The owner doesn't draw every change, but they notice when it's wrong and they are the one who gets asked. Put the owner on the diagram itself and in your diagram index.

4. Attach update triggers to events you already have

Don't rely on memory. Hook diagram updates to events that already happen:

• Pull requests. Add an architecture-impact checkbox to the PR template.
• ADRs. Every accepted architecture decision record links the diagram it changes, and the diagram is updated as part of accepting it.
• Incident postmortems. If the incident showed that the diagram was wrong or missing a dependency, fixing it becomes an action item.
• Quarterly review. Owners spend a few minutes per diagram confirming it still matches reality, then update the "last reviewed" date.

A PR template snippet:

## Architecture impact
- [ ] This change does not affect any architecture diagram
- [ ] I updated the affected diagram(s) and linked them below
- [ ] This needs an ADR (link):

5. Pick the right level of detail

Use levels instead of one giant picture. The C4 model gives you a shared vocabulary: a System Context view (people and systems), a Container view (applications and data stores) and a Component view inside one container. Higher levels change rarely and are cheap to keep accurate. Lower levels change often, so draw them only where people need them, and let the code be the source of truth below that.

A useful rule: if a diagram changes every sprint, it is probably drawn one level too deep.

6. Make date and version visible

Put the owner and a "last reviewed" date in a corner of every diagram. Readers can then judge trust at a glance: a diagram reviewed last month and one reviewed two years ago deserve different levels of confidence. Without a date, every diagram looks equally authoritative, which is worse than showing an old date.

7. Keep a diagram index

One page lists every diagram that matters:

The index makes gaps visible (no owner, an old date) and is the obvious starting point for the quarterly review.

8. Pair diagrams with ADRs

A diagram shows what the architecture is. It cannot show why. Architecture decision records fill that gap. Michael Nygard's original ADR format is short enough that people actually write them: title, status, context, decision, consequences. Link the ADR from the diagram and the diagram from the ADR:

# ADR-019: Move payment events to a dedicated queue

## Status
Accepted

## Context
Payment events share a queue with notifications.

## Decision
Give payment events their own queue.

## Consequences
One more queue to operate. Diagram "Payments: containers" updated.

When someone asks "why is it like this?" six months later, the answer is one click away.

How Archboard supports a living docs workflow

Archboard is a hosted architecture workspace, and most of the workflow above maps onto features it already has. Here is what it covers and where you still need your own process.

• One source of truth. Each diagram is a single document in your workspace, with autosave and revision snapshots. Free keeps the last 5 revisions; Pro keeps a year of revision history and Enterprise has no limit.
• Link, don't copy. Every plan has public share links (branded on Free). On Pro and Enterprise you can embed a diagram in your docs site via iframe, so the page shows the current version instead of a screenshot that drifts.
• History in your repo. Export the diagram as structured JSON and commit it next to the code or your ADRs. That gives you Git history and a review step for diagram changes, alongside the in-app revisions. The export is a manual step, so make it part of your PR habit.
• Notes on the canvas. Markdown nodes live on the canvas, so the owner, the "last reviewed" date, ADR links and a short legend sit inside the diagram rather than in a separate doc.
• The right level of detail. The C4 Model pack has Person, Software System, Container, Component and Database nodes plus boundaries. Nodes are first-class nodes with ports, and you wire them by connecting ports. Keep context and container views as separate diagrams.

A concrete setup for one system:

1. Create two diagrams: "Payments: Context" and "Payments: Containers".
2. Add a Markdown node in the top-left corner with owner, last-reviewed date and links to the related ADRs.
3. On Pro, embed the container view in the service's docs page. On Free, use the share link.
4. When a PR changes the architecture, update the diagram (or let the coding agent working on the PR do it through Archboard's MCP server), export the JSON and commit it to docs/architecture/ in the same PR.
5. Add both diagrams to your index page.

See the product overview for the full feature set, the C4 use case for C4-specific setups, and pricing for what each plan includes. Free gives you 3 diagrams, each with 15 diagram nodes plus 150 notes, text, stickers and mind map topics, to try a context view for one system; Pro unlocks unlimited diagrams and nodes when you document the whole platform.

Living docs checklist

• Every diagram has exactly one editable source
• Docs embed or link the live diagram, with no pasted screenshots
• Every diagram has a named owner, shown on the diagram
• The PR template includes an architecture-impact checkbox
• Accepted ADRs link the diagrams they change
• Postmortems ask "is the diagram still right?"
• Owners review their diagrams quarterly and update the date
• Diagrams are split by C4 level, not one giant picture
• A diagram index lists level, owner, last reviewed date and ADRs
• The diagram source (for example a JSON export) is committed next to the code

FAQ

How many diagrams should one system have? Start with a context view and a container view. Add component views only for the parts people regularly ask about. A few accurate diagrams beat many stale ones.

Should diagrams live in the repo or in a tool? Edit in one place and keep history where your team already reviews changes. With Archboard, you edit on the canvas and commit the JSON export to Git.

Start free — one seat, no credit card