Diagrams-as-Code in Git, Drift-Checked Against IaC

Tier: Core · Hands-on time: ~35 minutes

Live-infrastructure import is the most accurate diagramming approach because it reads actual configuration rather than anyone's memory. The architect's version of that insight: treat the diagram as a build artifact derived from IaC, and treat divergence as a signal. When the regenerated diagram disagrees with the committed one, either the infrastructure changed without the design being updated, or the design changed without being built — both are findings worth thirty-five minutes.

When to use

• •
  A system has both a maintained diagram and maintained Terraform, and nobody is sure they still agree.
• •
  You are establishing docs-as-code practice for a team and want diagrams in the PR workflow, not in a drawing tool's cloud account.
• •
  Post-incident or pre-audit: you need to certify that the architecture docs reflect deployed reality.

Skip AI when there is no IaC — a drift check needs a machine-readable source of truth; hand-managed consoles give you nothing to diff against.

Prerequisites

• Claude Code (or comparable repo-aware agent) with read access to the infrastructure repo.
• Terraform sources and/or a recent terraform show outputplan/state output gives deployed truth; .tf files give declared truth. Know which one you are diffing against, and never hand the agent state files containing secrets — use terraform show output reviewed for sensitive values, or the .tf sources.
• The committed diagram sourceMermaid or D2, ideally born from pb-07 with its intent inventory comment.
• A git branch for the regenerated artifacts and the drift report.

The workflow

1. 1.

   Establish the mapping convention once. Decide and write down, in a DIAGRAMS.md, what the diagram shows from the IaC: which resource types appear (compute, data stores, queues, gateways — usually not IAM glue or log groups), what granularity (module = box is a good default), and which edges are drawn (network paths and data flows, not every security-group reference). Without a convention, every drift check drowns in noise.

2. 2.

   Have the agent regenerate from IaC.

   Copy

   Read infra/ (Terraform) for the orbit-docs-copilot stack. Following the
   conventions in docs/DIAGRAMS.md, generate docs/diagrams/system.generated.mmd
   showing: compute services, data stores, queues/topics, gateways, and the
   VPC/subnet boundaries, with edges for network paths and data flows you
   can actually evidence from the code (security group rules, IAM-granted
   access, environment-variable wiring, subnet placement).
   
   Rules:
   - Every node and edge gets a trailing comment naming the Terraform
     resource(s) it derives from.
   - If you cannot evidence an edge from code, do not draw it — list it
     under "UNEVIDENCED" at the bottom.
   - Do not consult the existing system.mmd — this must be an independent
     derivation.
   

3. 3.

   Diff generated against committed — with the agent narrating. "Compare docs/diagrams/system.mmd (design intent) with system.generated.mmd (derived from IaC). Report three lists: in design but not deployed; deployed but not in design; present in both but different (labels, boundaries, direction). Cite the Terraform resource for every deployed-side claim." The resource citations are what make findings checkable in minutes.

4. 4.

   Triage every drift finding to a cause. Each divergence is one of: infrastructure moved ahead of docs (update the diagram — most common), design moved ahead of build (expected, note the ticket), the agent misread the IaC (it happens — the resource citation lets you disprove it fast), or the convention is ambiguous (fix DIAGRAMS.md). The triage note, not the diff, is the deliverable — Anita's first run found a NAT path in Terraform that the design said should not exist, which was a real security finding, not a doc bug.

5. 5.

   Fold accepted changes into the canonical diagram and PR it. Never let system.generated.mmd replace system.mmd wholesale — the canonical diagram carries intent (grouping, labels, annotations) the generator cannot know. Port the accepted deltas by hand or with scoped agent edits, keep the generated file as evidence, and open a PR containing diagram change + drift report + triage notes.

6. 6.

   Schedule it. Wire the regeneration and diff into CI (weekly, or on merges touching infra/), failing softly with a posted drift report rather than blocking. Drift checking you remember to do monthly is drift checking you do quarterly.

Verify before you trust it

• Spot-check resource citations. Pick three generated edges and read the cited Terraform. An agent that inferred an edge from a variable name rather than an actual rule will be exposed by its own citation — that is why you demanded them.
• Check the UNEVIDENCED list against reality. Edges the agent could not prove often exist via mechanisms outside the repo (peering managed elsewhere, ClickOps exceptions). Each one is either missing IaC (a finding) or missing convention (fix the doc).
• Confirm the negative claims. "In design but not deployed" findings deserve a console or terraform state list check before you announce them — the agent may simply have missed a module. Never escalate a drift finding you have not reproduced.
• Diagram still verifies against intent. After merging updates, rerun the pb-07 edge-by-edge check against the intent inventory. Drift-syncing must not quietly rewrite the design's meaning.

Restricted-environment variant

Client Terraform is client-confidential infrastructure detail — often the most sensitive artifact you hold. Run the agent inside the approved boundary: Claude Code against a client-tenancy endpoint (Bedrock/Azure OpenAI in the client's subscription), or a local model for the generation step. Where no AI may touch the IaC at all, keep the pattern and drop the model: deterministic tools (Inframap-class generators, terraform graph post-processing) produce the deployed-truth diagram, and you do the diff reading yourself — the git-plus-schedule discipline is the durable part of this playbook, with or without the AI acceleration.