C4 Architecture Diagrams → Mermaid

Emit valid Mermaid flowchart code blocks that follow C4 methodology. Never use experimental C4Context/C4Container/C4Component/C4Deployment syntax — it breaks across Mermaid versions.

References (load on demand): abstractions · diagram selection · anti-patterns · mermaid gotchas · templates: context · container · component · deployment · dynamic · landscape

Validation: node scripts/validate_mermaid.mjs <file>. On first use run npm install in scripts/.

Rendering Primitives

Node label formula

["<b>Name</b><br/><i>[Stereotype: Technology]</i><br/>One-line responsibility"]

Shapes → C4 element types

Boundaries = subgraphs

subgraph systemName ["System Name — [Software System]"]
  direction TB
  Container1["..."]
  Container2["..."]
end

Nest subgraphs for deployment nodes, trust boundaries, or container internals.

Edges

Label every edge with purpose, not protocol:

A -- "sends commands to" --> B
A -. "reads config from" .-> C

Protocol belongs one level down (container edges show tech on container diagrams, not on context diagrams).

Title (mandatory)

---
title: System Name — View Type
---
flowchart TB
  ...

Legend (mandatory on structural diagrams)

subgraph Legend["Legend"]
  direction LR
  LP(["Person"]):::person
  LS["Internal System"]:::system
  LE["External System"]:::external
  LP ~~~ LS ~~~ LE
end

classDef person fill:#08427b,color:#fff,stroke:#052e56
classDef system fill:#1168bd,color:#fff,stroke:#0b4884
classDef external fill:#999999,color:#fff,stroke:#6b6b6b

Adapt legend entries to match what appears in the diagram. Use ~~~ (invisible link) for layout.

Colors

Colors are not prescribed by C4 — adapt to context. Be consistent within and across diagrams.

Workflow

Step 0 — Intake

Ask:

1. What system (or landscape) are we diagramming?
2. Who is the audience? (everyone / technical / architects+devs)
3. What's the goal? (communicate to stakeholders / onboard devs / design review / document current state)
4. Do you already have named abstractions (systems, containers, components) or should we identify them together?

Sensible defaults if user skips fields. Proceed once enough context exists.

Step 1 — Identify Abstractions

Before drawing anything, map the architecture to C4 vocabulary:

• Software system — what a single team owns. The team boundary = system boundary.
• Container — a running application or data store. Not Docker (though often maps to Docker).
• Component — a grouping of related code behind an interface, inside a container. Not separately deployable.

Load references/abstractions.md for:

• Microservice decision: same team → containers; different team → separate system
• Queues/topics: model as individual containers (data stores), not a single "message bus"
• Shared libraries: not containers — show as component copies with color coding

Step 2 — Select Diagram Type

Load references/diagram-selection.md for detail. Confirm choice with user.

Most teams need only System Context + Container. Don't over-diagram.

Step 3 — Produce Diagram

1. Load the template for the chosen type from assets/templates/
2. Apply the rendering primitives from this file
3. Use flowchart TB for hierarchical views, flowchart LR for pipelines/flows
4. Keep under 25 nodes — split into focused sub-views if larger
5. Use click NodeID "url" "tooltip" for drill-down links between diagrams

Step 4 — Validate Syntax

node scripts/validate_mermaid.mjs diagram.mmd

Or pipe directly:

echo '<mermaid code>' | node scripts/validate_mermaid.mjs --strict -

Fix errors. Re-run until ✓ Valid. Use --strict to also reject banned C4* keywords.

Step 5 — Self-Check (notation quality)

• Title present (YAML frontmatter in the mermaid block)
• Every element has [Stereotype] in label
• Every element has one-line responsibility description
• Every container/component has technology stated
• Every edge is labeled with purpose
• Every edge is unidirectional (bidirectional only when both directions meaningful)
• Legend subgraph present (structural diagrams)
• Diagram has ≤ 25 nodes
• No C4Context / C4Container / C4Component / C4Deployment keywords
• Labels with HTML or special chars are quoted

Hard Rules

1. NEVER use C4Context, C4Container, C4Component, C4Deployment, C4Dynamic — experimental, breaks across versions.
2. ALWAYS use flowchart + subgraph for structural diagrams, sequenceDiagram for temporal interactions.
3. ALWAYS quote labels containing HTML (<b>, <i>, <br/>) or special chars.
4. ALWAYS include Legend subgraph in structural diagrams.
5. ALWAYS validate with scripts/validate_mermaid.mjs before delivering.
6. Purpose on edges, not protocol. Protocol belongs one level down.
7. Abstraction labels ([Person], [Software System], [Container: Tech], [Component: Tech]) are mandatory — they tell the reader what level they are looking at.

Anti-Patterns (top 5)

1. Hub-and-spoke message bus — modeling RabbitMQ/Kafka as one container. Model each queue/topic as its own container instead. See anti-patterns.
2. Microservice as component — a microservice is a container (or group of containers), never a component. Components are not separately deployable.
3. Mixing abstraction levels — a context diagram showing containers, or a container diagram showing components from other systems. Each diagram has one scope.
4. Unlabeled edges — every arrow must say what it does. "Uses" is too vague. Be specific: "sends payment requests to", "reads user profiles from".
5. Missing boundaries — if your container diagram doesn't have a subgraph showing the system boundary, the reader can't tell what's inside vs. outside.

Full catalog: references/anti-patterns.md

Mermaid Syntax Pitfalls

Full list: references/mermaid-gotchas.md