How to detect stale architecture diagrams: five signals you can check today and one you can automate

The cheapest check is two dates. When the diagram lives in the repo, compare its last commit against the last commit touching the infrastructure directory: git log -1 --format=%cs -- docs/architecture.png against the same command for infra/ or terraform/. When it lives on a wiki, compare the page history against your deploy log or the merge dates of recent infrastructure PRs.

One infra change since the last diagram edit proves nothing, because plenty of changes are invisible at diagram altitude. Three or more merges that added, removed, or renamed a component since the diagram was touched is a different story. The date gap does not tell you what is wrong, only that nobody has looked since things moved.

Every label on an architecture diagram should correspond to something findable in the codebase: a service directory, a Terraform resource, a Helm release, a topic name. Pick five node labels and grep the repo for each. A diagram node called billing-worker while grep -r billing-worker returns nothing is a confirmed lie: the service was renamed, merged into another, or deleted, and the diagram kept it alive.

Run the check in reverse too. List the directories under services/ or the entries in your service catalog, and look for names the diagram does not carry. Missing components are more dangerous than ghost ones, because a reader cannot be confused by a box that is not there. They simply never learn the component exists.

Counting is cruder than grepping but faster at scale. terraform state list | wc -l gives you what Terraform manages. kubectl get deployments -A gives you what actually runs. Your service catalog gives you what the org believes it owns. Count the boxes on the diagram and compare. Exact equality is not the goal, a diagram legitimately abstracts. A diagram showing 12 services in front of a catalog listing 31 has stopped abstracting and started omitting.

The same check works per zone: if the diagram shows two components in the ingestion layer and the pipeline code defines six sources, the stale region is localized, which also tells you where to start fixing.

The count check becomes a real gate once the diagram maintains a machine-readable component list next to it, one name per line. A CI job then diffs that list against what Terraform reports and fails the build when they diverge. Scope the state query to the resource types that appear on the diagram, ECS services, Cloud Run services, Kubernetes deployments, whatever your unit of box is.

Be honest about what this verifies: presence, not correctness. The gate catches an added or deleted service, which in practice is most diagram drift. It cannot catch a wrong arrow. Treat a red build as a prompt to regenerate the diagram, not as proof the picture is otherwise fine.

# ci/check-diagram-components.sh
# Fails when the diagram's component list drifts from Terraform state.
terraform state list \
  | grep -oP 'aws_ecs_service\.\K\w+' \
  | sort -u > /tmp/live-services.txt

sort -u docs/architecture-components.txt > /tmp/documented-services.txt

if ! diff -u /tmp/documented-services.txt /tmp/live-services.txt; then
  echo "Architecture diagram no longer matches Terraform state." >&2
  exit 1
fi

A last-verified badge is a visible line on the diagram or the page around it: verified against production on 2026-08-01 by a named person. It is deliberately distinct from last-edited. An edit can be a typo fix; verification is a human attesting that the picture still matches the system. The badge gives readers a trust signal and gives you a number to gate on: a freshness check in CI can fail when the badge date is older than 90 days, the same pattern as the freshness gates in a docs pipeline.

The absence of any badge is itself the signal. A diagram that has never recorded a verification has, statistically, never had one.

Detection is only useful if repair is cheap, and repair has two halves. The first is redrawing. With Datadef's MCP server (registry name io.datadef/mcp), an agent like Claude Code or Cursor connected to your repo can update the diagram from what the code actually contains: run it after the CI gate goes red, on a schedule, or during review. To be precise, Datadef does not watch your repository and nothing detects code changes by itself. The regeneration is one agent call or one CI command away, which is exactly why the detection signals above matter. Connecting an agent needs an API key, available on paid plans.

The second half is propagation, and that one is automatic. A diagram embedded by URL in your README, Notion, or Confluence follows its source: Datadef serves the image with a five minute cache lifetime, so the repaired diagram shows up everywhere it is embedded within minutes. The embed URLs exist only for projects shared public, a real trade-off for confidential architectures. For the decision of when redrawing is worth it at all, see when to regenerate an architecture diagram, and for the wider problem beyond diagrams, stale documentation.

• Stale documentation
• Documentation drift
• When to regenerate an architecture diagram
• Documentation checks in CI
• The Datadef MCP diagram server