Architecture Diagrams from Natural Language — with Verification

Tier: Foundation · Hands-on time: ~25 minutes

Diagram generation from natural language is a mature 2026 tool class — Mermaid or D2 through a coding assistant, or dedicated generators like Eraser AI. The speed is real: the first draft that used to cost an afternoon in a drawing tool now costs a prompt. What has not changed is accountability. A diagram is a claim about how the system works, and models pad drafts with components you never mentioned, invent edges that "usually" exist, and label queues as topics. Every box and every arrow gets checked against intent before the diagram earns a filename.

When to use

• •
  A design exists in your head or in prose and needs its first visual for a review, proposal, or HLD.
• •
  An existing diagram needs restructuring (new altitude, different audience) and redrawing from scratch is the honest path.
• •
  You are moving a whiteboard photo into a maintainable text-based format.

Skip AI when you are changing two boxes on a diagram whose source you own — direct edits beat regenerate-and-reverify.

Prerequisites

• A coding assistant or chat model that emits Mermaid or D2text-based diagram code is the default: git-friendly, diffable, and the foundation for drift-checking (pb-08). Eraser AI-class tools are the alternative when stakeholders need their visual style.
• A written design intentthe paragraph or bullet list that says what the system actually contains. This is the verification oracle; without it you are checking the diagram against your mood.
• A rendererMermaid Live, VS Code preview, or D2 CLI.

The workflow

1. 1.

   Write the intent as an inventory, not a story. List components, then connections, then boundaries. Anita's brief for orbit-docs-copilot: "Components: web client, API gateway, copilot service, retrieval service, Postgres+pgvector, embedding pipeline, LLM gateway, external model API. Connections: client→gateway→copilot; copilot→retrieval→pgvector; pipeline→pgvector (write path); copilot→LLM gateway→model API. Boundaries: everything except the model API inside the EU VPC." An inventory converts verification from an aesthetic judgment into a checklist.

2. 2.

   Prompt with the inventory and a no-invention rule.

   Copy

   Generate a Mermaid flowchart (architecture style, top-down) from this
   inventory. Rules:
   - Include ONLY the listed components and edges. Do not add components
     that systems like this "usually" have (no cache, no CDN, no queue
     unless listed).
   - Every edge gets a short label naming the interaction (HTTPS, SQL,
     embeddings write).
   - Draw the EU VPC as a subgraph boundary; the external model API sits
     outside it.
   - If the inventory seems to be missing an edge a working system would
     need, add a comment line listing the QUESTION — do not draw the edge.
   ###
   [paste inventory]
   

3. 3.

   Render, then verify edge by edge. This is the step that makes the playbook. Take the intent inventory and tick off: every listed component present? every listed edge present, correctly directed, correctly labeled? Then invert it: every drawn box in the inventory? every drawn arrow in the inventory? Anything in the diagram but not the intent is either a model invention (delete) or a real gap in your intent (update the intent first, then the diagram). The QUESTION comments are often the most valuable output — "how does the embedding pipeline get documents?" caught a genuinely missing ingestion edge in Anita's first pass.

4. 4.

   Fix in the source, not the picture. Iterate in the same conversation with scoped edits: "Remove the Redis node; change the pipeline→pgvector label to 'batch upsert'; nothing else changes." Regenerating from scratch on each tweak re-rolls every hallucination dice — scoped edits converge.

5. 5.

   Set the altitude deliberately. One diagram per audience: the exec version collapses the retrieval internals into one box; the build-team version shows ports and protocols. Ask the model to derive the collapsed view from the verified detailed source so the two cannot disagree — never maintain two hand-divergent versions of the truth.

6. 6.

   Commit the source next to the design. The .mmd/.d2 file goes in the repo with the design doc, with the intent inventory as a comment block at the top. That pairing is what pb-08 turns into a drift-checked, living diagram.

Verify before you trust it

• Two-way edge check. Intent→diagram: nothing missing. Diagram→intent: nothing invented. Both directions, every edge — the invented direction is where plausibility machines earn the name.
• Boundary placement is exact. Subgraph membership is a security claim: a database drawn inside the VPC that actually sits in a vendor's tenancy is a compliance misstatement waiting for an auditor. Check every boundary against reality, not intent alone.
• Labels name real protocols and real services. Models write "gRPC" on REST edges and label generic queues with a specific vendor product you do not use. Any service name the diagram introduces that you did not — verify it exists in the design, or delete it.
• Arrow direction matches data or call flow — pick one and say which. Mixed semantics (some arrows are calls, some are data) is the classic reviewer trap; add a legend line stating the convention.

Restricted-environment variant

The intent inventory usually contains client system names — check the pb-03 register before pasting. Redaction is nearly free here: [ORDER-SYSTEM], [CLIENT-IDP] render identically, and you can restore real labels in a local find-and-replace after generation. Where even structure is restricted, Mermaid/D2 via a local Ollama coding model works well — diagram code is a language small models handle — or use the client-tenancy endpoint. Diagram files are design artifacts under the MSA: store them in the engagement repo, not personal drives, whichever path generated them.