Mermaid Architecture Diagrams

Produce diagrams that are correct, legible in print, and consistent as a set — not just syntactically valid Mermaid.

The one non-negotiable rule

Never trust unrendered diagram code. Mermaid layout is emergent: label widths, edge routing, and subgraph sizing only exist after rendering. The loop is:

1. Author the .mmd
2. Render it: scripts/render-mmd.sh diagram.mmd
3. Look at the preview image (the script writes a *-preview.png sized for inspection)
4. Fix clipping, overlaps, label collisions, edge crossings — re-render
5. Repeat until clean (minimum one fix round; diagrams are never right first try)

A diagram you haven't looked at is a draft, not a deliverable.

Workflow