When to regenerate an architecture diagram: event triggers beat calendars

Architecture changes arrive in bursts: a migration week rewires half the system, then months pass quietly. A calendar samples that process at fixed intervals, so it is almost always wrong, stale right after the burst and redundant during the quiet. An event trigger fires exactly when the truth changed, which is the only moment the diagram needs attention.

Calendars keep one job: the floor. A quarterly check catches the slow drift no single event announces, renamed teams, deprecated services still drawn as alive, and confirms the trigger wiring itself still works. If you want the cadence question answered on its own, how often should architecture diagrams be updated covers it; this page is about designing the triggers.

Five events cover most drift. First, a merge touching infrastructure paths: Terraform, Kubernetes manifests, Dockerfiles, compose files, CI deploy configs. These files are where topology actually changes, and a path filter makes the trigger mechanical.

Second, a new service, detectable as a new deployable unit: a fresh Dockerfile, a new Terraform module, a new entry in the deploy pipeline. New nodes are the single most common thing missing from old diagrams. Third, an incident postmortem: if the diagram was wrong or unhelpful during the incident, fixing it is a natural action item while the gap is fresh.

Fourth, the start of an onboarding cohort: new hires are the readers most damaged by a stale diagram and least able to detect it, so regenerate the overview before they calibrate on fiction. Fifth, the quarterly floor for anything no event has touched.

The merge trigger is the one worth automating, and CI path filters make it precise: the job runs only when a push to main touches the paths where topology lives. The job checks out the repo and asks an agent connected to the Datadef MCP server to update the diagram from what the repository now declares.

To be precise about the mechanics: Datadef does not watch repositories and nothing auto-detects the change. The CI job is what invokes the agent, and the agent reads the repo and calls the diagram tools. Connecting an agent requires a Datadef API key, available on paid plans. The MCP diagram server guide covers the setup; the workflow below assumes the repo carries an .mcp.json declaring the server.

# .github/workflows/architecture-diagram.yml
name: architecture-diagram
on:
  push:
    branches: [main]
    paths:
      - 'terraform/**'
      - 'k8s/**'
      - 'docker-compose*.yml'
      - 'services/*/Dockerfile'
jobs:
  regenerate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update the diagram from the repo
        run: >
          claude -p "Read this repository's Terraform, manifests, and compose
          files, then update our platform diagram through the Datadef MCP
          server so it matches what this commit deploys."
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Not every diagram earns every trigger. The system overview, the one in the README and the onboarding doc, wants the new-service trigger, the onboarding trigger, and the quarterly floor; per-merge regeneration would churn it for changes readers of an overview never see. The infrastructure and network views want the path-filtered merge trigger, because their whole value is matching what is deployed. A Terraform-derived diagram is the cleanest case: its source of truth is exactly the filtered path set.

Incident and failover views want the postmortem trigger plus any merge touching the components they draw, because their failure mode is the most expensive: being wrong during an outage. The rule underneath: the more a diagram is consulted under pressure, the more event-driven its updates must be.

Event triggers were always the right policy; they were just unaffordable. When updating meant an engineer rearranging boxes for an afternoon, firing that cost on every infra merge was absurd, so teams rationally batched updates into quarterly sessions and lived with the drift between them.

One-command regeneration inverts the math. When the update is an agent call, the marginal cost of a trigger firing approaches the cost of reviewing a diff, so you can afford to fire liberally and let humans review the output rather than produce it. It also simplifies the drift question itself: instead of wondering whether the diagram is stale, regenerate and compare. Detecting stale diagrams covers that comparison in detail.

• MCP diagram server
• How often should architecture diagrams be updated
• How to detect stale diagrams
• A living diagram from Terraform
• Architecture diagram from code