Every team has the diagram: drawn for a design review two years ago, wrong about three services, still pasted into every new deck. Hand-maintained diagrams drift the day after they are drawn.
Tier: Foundation · Workflow area: Documentation
The fix is to make code the source: an AI agent reads the actual repo — imports, service calls, queue topics, infra definitions — and emits Mermaid or C4 text that lives in the repo, gets reviewed in PRs, and gets regenerated when reality changes. Diagrams-as-code plus AI generation turns "update the diagram" from an act of archaeology into a diff.
Skip aspirational "target architecture" diagrams — those are design artifacts, drawn from intent, and should differ from code. Never let the AI generate those from the repo; it can only draw what is.
Generate the container view from deployment truth. Start at the level infra files define:
Read docker-compose.yml, terraform/, and .github/workflows/. Produce a
Mermaid C4-style container diagram:
- One node per deployable/datastore/queue actually defined (cite the file
defining each).
- Edges only for communication you can evidence in code or config: HTTP
client base-URLs, queue topic names, DB connection strings. Cite the
evidence file per edge.
- Mark any suspected-but-unevidenced edge with a dashed line and "?".
Output as a mermaid block plus the citation list.
Generate component views only for the areas that need them. Per subsystem: From services/billing/ imports and package structure, produce a component diagram of its internal modules and their dependency direction. Collapse anything under 100 lines into its parent. Flag dependency-direction violations (lower layers importing upper). The violations flag routinely surfaces real architecture erosion — treat those as findings, not diagram noise.
Audit the edges — that is where diagrams lie. Nodes are easy; edges are claims. For each edge, check the cited evidence: is that HTTP call still live or behind a dead feature flag? Is the queue topic still consumed? Delete or dash anything unproven. Ten minutes of edge audit is the difference between a diagram and a rumor.
Commit the text, render on demand. Diagrams live as .mmd/Structurizr DSL in docs/architecture/, reviewed via PR like any code. The PR review question is precise: "does this edge exist?" — answerable, unlike "does this picture feel right?"
Wire regeneration to drift. Two options by maturity: (a) lightweight — a CI job flags when files cited as diagram evidence change (git diff --name-only against the citation list) and opens an issue to regenerate; (b) full — a scheduled agent regenerates the diagram and opens a PR with the diff, which a human reviews. The rendered diff of a Mermaid change ("edge added: orders → notifications") is itself a nice architecture-change alert.
Deterministic extractors (pydeps, madge, Structurizr automatic extraction, Terraform graph) beat an LLM for raw dependency edges — they cannot hallucinate. The AI's value is on top: choosing altitude, collapsing noise, naming clusters meaningfully, and drafting the Mermaid. Feed extractor output into the prompt when the tools exist for your stack.
Infra files are the most sensitive inputs here — Terraform and compose files contain account IDs, internal hostnames, sometimes secrets that escaped the vault. Scrub or use the sanctioned in-tenancy agent. Strong offline path: deterministic extractors (madge, pydeps, terraform graph) are all local, and a local Ollama model converts their output into clean Mermaid competently — this workflow degrades gracefully because the hard evidence comes from tools, not the model. Client-facing diagrams get one extra pass: strip internal hostnames and account identifiers before any deck leaves the building.