How often should architecture diagrams be updated: on merge for generated views, quarterly for the rest

On merge for anything you can regenerate, and a quarterly verification floor for everything else. The reasoning: a diagram is wrong from the moment the system diverges from it, so the ideal update moment is the merge that causes the divergence. What stops teams from updating at that moment is cost, not ignorance. When an update costs 45 minutes of box dragging, people batch updates and the diagram spends most of its life wrong. When an update costs one command, updating on merge stops being aspirational.

A useful test: if a new engineer used this diagram to debug production today, what on it would send them in the wrong direction? If the answer is anything load-bearing, the diagram missed its update window, and no cadence policy matters until that is fixed.

Different zoom levels change at different speeds, so one cadence for all diagrams is wrong twice. A context-level view, the system plus its external dependencies, changes a few times a year: new vendor, new upstream consumer, a system retired. A quarterly verification pass genuinely covers it.

A container or service-level view changes monthly on most teams: a service split, a new queue, a datastore migration. This level needs event-triggered updates, with the quarterly pass as a backstop for the events nobody flagged.

Component-level and pipeline-level views can change weekly. Hand-maintaining diagrams at this level is a losing trade on most teams, and the honest choice is either to generate them from the source or not to keep them at all. A wrong detailed diagram costs more than no diagram, because detail signals authority.

Calendar reviews catch drift late; events catch it at the source. The trigger list worth wiring into your workflow is short: a service added or removed, a dependency between services added or removed, a datastore or queue swapped, an external integration changed, and any incident where the diagram sent a responder the wrong way. That last one is a free audit: the postmortem already proved the diagram lied.

The calendar still matters as a floor, because triggers get skipped during crunch. Quarterly is the widest floor that still catches drift within the same planning cycle that caused it. The mechanics of a verification pass, minutes per doc rather than hours, are covered in documentation review cadence.

The variable teams control is cost per update. Datadef ships an MCP server, registry name io.datadef/mcp, so an agent like Claude Code or Cursor connected to it can read the repository and update the diagram to match: after a merge, in a scheduled job, or on request during code review. To be precise about what that is not: Datadef does not watch your repository and nothing detects code changes on its own. The update is one agent call or one CI command away, which is what makes an on-merge cadence realistic. Connecting an agent needs an API key, available on paid plans.

When regeneration is cheap, the cadence question inverts: instead of asking how often you can afford to update, you ask which merges are worth a redraw, which is the subject of when to regenerate an architecture diagram.

# Regenerate the diagram when architecture-shaped paths change on main.
# The agent reads the repo and updates the diagram through the Datadef
# MCP server (configured in the repo's .mcp.json).
name: redraw-architecture-diagram
on:
  push:
    branches: [main]
    paths: ['services/**', 'infra/**', 'docker-compose*.yml']
jobs:
  redraw:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Reconcile diagram with the repo
        run: |
          claude -p "Compare our platform diagram to the services and infra
          in this repo, and update the diagram via Datadef where they diverge."
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Context diagrams: verify quarterly, update on vendor and boundary changes. Container diagrams: update on the trigger list, verify quarterly, generate if the team ships weekly. Component diagrams: generate or delete. Write the policy next to the diagrams it governs, name an owner per diagram, and treat an incident-revealed lie as a sev-2 against the doc.

If diagrams have drifted so far that nobody trusts them, cadence is the wrong first move; recovery is, and that is covered in documentation drift.

• When to regenerate an architecture diagram
• Documentation review cadence
• Documentation drift
• MCP diagram server