Generate Architecture Diagrams and ADRs from Live Infrastructure

Tier: Foundation · Workflow area: Runbooks, docs & knowledge

This playbook derives diagrams-as-code (Mermaid/D2) and narrative directly from your IaC — so the source of truth generates the picture, not the other way round — schedules a drift check so the diagram stays honest, and scaffolds ADRs with AI-drafted options analysis while keeping the decision itself unambiguously human.

When to use

• •
  Onboarding, audit, or client review needs a current architecture view and the wiki diagram is two migrations old.
• •
  You are proposing an infra change (new queue, region, gateway) and owe the team an ADR.
• •
  You want diagrams reviewed in PRs alongside the Terraform that changes them.

Skip AI for a whiteboard conversation — generate durable artifacts, not throwaway sketches.

Prerequisites

• •
  IaC in a repo: Terraform/OpenTofu (plus Helm/K8s manifests if relevant). Read access is enough; no state secrets needed.
• •
  A repo-aware assistant (Claude Code, Cursor, Copilot) able to read the whole module tree.
• •
  A renderer for Mermaid or D2 in your docs pipeline (most git platforms render Mermaid natively).
• •
  For ADR cost numbers: Infracost installed, or recent cost exports.

The workflow

1. 1.

   Generate the diagram from IaC, with an explicit scope.

   Copy

   Read infra/ (Terraform) and helm/. Produce a Mermaid architecture diagram at
   the level of: VPCs/networks, compute (clusters, node groups), data stores,
   queues/topics, load balancers/gateways, and external SaaS dependencies.
   
   Rules:
   - Only include resources that exist in the code. No idealized components.
   - Group by subsystem; label edges with protocol/purpose (HTTPS, SQS, gRPC).
   - Omit per-environment duplication: draw prod, note diffs for staging below.
   - After the diagram, list any resources you could not classify.
   

2. 2.

   Verify against the source, not your memory. Walk each node and edge back to a Terraform resource (ask the assistant to emit a node→resource-address mapping table). Delete anything unmapped. Render the diagram and fix syntax before committing.

3. 3.

   Add the narrative. One page: what talks to what and why, blast-radius notes, and the three things newcomers always get wrong. The assistant drafts from the diagram + code; you correct intent — the code shows what, only humans know why.

4. 4.

   Commit next to the IaC and wire the drift check. Put docs/architecture.md in the same repo. Add a scheduled CI job (weekly, or on merge to infra paths) that re-runs step 1 and diffs the node→resource mapping against the committed one; a mismatch opens an issue or a draft PR with the regenerated diagram. Diagram drift is now visible instead of silent.

5. 5.

   Scaffold the ADR when a decision looms.

   Copy

   Draft an ADR: "Choose a message bus for order events" using our ADR template.
   Options to analyze: SQS+SNS, MSK (Kafka), self-managed NATS.
   For each option: operational burden for a 4-person platform team, lock-in,
   failure modes, migration path, and rough monthly cost (I will supply
   Infracost/pricing numbers — leave placeholders).
   Then: a comparison table, and the questions we must answer before deciding.
   Do NOT write the Decision section.
   

6. 6.

   Fill in real numbers, decide, and record. Run infracost breakdown on candidate configs (or pull vendor pricing) and replace the placeholders — never let the model guess prices. Discuss with the team, write the Decision and Consequences sections yourself, and merge the ADR with named deciders and a date.

Tool variants

• Claude Code / repo-aware assistant + Mermaid: the default path above; Mermaid renders in GitHub/GitLab without tooling.
• D2: better layout control for large estates; render in CI with the d2 CLI and commit the SVG next to the source.
• Inframap / terraform graph: deterministic generators make a good cross-check — if the LLM diagram disagrees with the generated graph, believe the generator and investigate.

Verification

• •
  Every diagram node and edge maps to a real resource address (mapping table checked in review).
• •
  The rendered diagram compiles cleanly in your docs pipeline.
• •
  Drift-check job runs green on schedule, and its most recent diff was triaged.
• •
  ADR cost figures trace to an Infracost run or vendor quote, not model output; Decision section authored by a named human.

Pitfalls

• The idealized-architecture hallucination. Models happily draw the reference architecture you should have. The only-in-code rule and mapping table are your defense.
• One diagram to rule them all. A single diagram with 200 nodes helps nobody. Generate one overview plus per-subsystem diagrams, each scoped in its own prompt.
• Cost numbers from the model. LLM-recalled cloud pricing is stale or invented. Numbers come from Infracost or the console, always.
• ADRs written after the decision. Scaffolding is cheap now — write the ADR while options are genuinely open, or it becomes justification theater.

Restricted-environment variant

IaC reveals your (or your client's) entire attack surface:

• •
  For client estates, run generation inside the client's approved tenancy or on a self-hosted model; the Terraform itself must not leave their boundary.
• •
  Sanitize the committed diagram if docs live in a broader-access repo: account IDs, CIDR blocks, and bucket names can be labeled generically without losing architectural meaning.
• •
  ADRs discussing client-commercial terms (committed spend, discounts) stay in the client's own doc system.

Success criteria

• •
  Architecture docs regenerate in minutes and PR reviewers actually look at the diagram diff.
• •
  The drift check has flagged at least one real divergence before a human noticed it.
• •
  ADRs exist for the last three significant infra decisions, each with verifiable cost numbers and a human-authored decision.
• •
  New joiners cite the generated docs as their onboarding map.