Skip to main content

ADR-0017 — Mermaid for architecture diagrams

  • Status: Accepted
  • Date: 2026-05-08
  • Decision-makers: Tom Anderson

Context​

The bible needs C4 diagrams, sequence diagrams, state machines, and ER diagrams. Options:

  • Mermaid — text-based, renders inline in Markdown/MDX, version-controlled, Docusaurus has a plugin
  • PlantUML — text-based, more powerful, requires Java to render
  • Lucidchart / draw.io — GUI-based, produces PNG/SVG to embed
  • Excalidraw — sketchy aesthetic, files committed as .excalidraw
  • C4 model rendered via Structurizr — purpose-built for C4, learning curve

The key axis: are diagrams source-of-truth (version-controlled, diffable, code-reviewable) or artifacts (binary blobs)?

For docs that change as the system changes, source-of-truth wins. PNGs go stale; nobody updates them.

Mermaid specifically:

  • Already integrated with Docusaurus via @docusaurus/theme-mermaid
  • Supports flowcharts, sequence, state, ER, gantt, mindmap, C4 (limited)
  • Renders client-side; no build-time overhead
  • Diffs cleanly in PRs

Decision​

All bible diagrams are Mermaid, embedded in .mdx files. No external diagram tools, no committed PNGs.

\```mermaid
graph TB
  A --> B
\```

Diagram conventions:

  • Sequence diagrams for cross-component flows (data flow diagrams)
  • graph TB (top-bottom) for C4 component/container/context diagrams
  • stateDiagram-v2 for lifecycles
  • erDiagram for entity relationships (when needed)
  • Class definitions at the top of each diagram for consistent coloring

Color tokens used:

  • Internal systems: #c8410c (Kvick orange)
  • Internal containers: same orange
  • External services: #f6f1eb (parchment, brand background)
  • Storage: #1e3a5f (deep blue)
  • Routes/controllers: #3b82f6 (mid-blue)

Consequences​

Positive:

  • Diagrams are source-controlled and reviewable
  • Updates to the system can be reflected in the diagram in the same PR
  • No external tool licenses or vendor lock-in
  • Renders the same on local dev, in PRs, and on the deployed bible
  • AI assistants can read and modify diagrams without leaving the editor

Negative:

  • Mermaid's expressive limits — some advanced layouts are awkward
  • Mermaid's C4-specific syntax is less mature; we approximate with graph TB
  • Renders are deterministic but layout sometimes surprises (especially for dense graphs)

Mitigations:

  • When a diagram needs to be very specific (e.g., a printable network architecture poster), drop a one-off SVG into static/img/ and link it; rare case
  • For very complex diagrams, split into multiple smaller diagrams

Notes​

The bible's docusaurus.config.ts already enables @docusaurus/theme-mermaid and sets markdown.mermaid = true. New .mdx pages just need to drop a ```mermaid block.

See also​