mermaid-diagrams

Mermaid Diagrams

Author, render, and share Mermaid diagrams. The standard format for all docs/architecture/ artifacts in this repo. Renders natively in GitHub, GitLab, Obsidian, and Claude Code — no images needed.

Diagram Type Selection

See rules/mermaid.md for the full selection guide. Summary:

Need	Type
System / service overview	C4Context, C4Container
Component graph	graph TD
API / message flows	sequenceDiagram
Database schema	erDiagram
State machines	stateDiagram-v2
Logic / control flow	flowchart
Git branching	gitGraph
Schedule / milestones	gantt
Chronological events	timeline
User journey	journey
Hierarchy / brainstorming	mindmap
Metrics / trends	xychart-beta
Data volumes	sankey-beta
OOP structures	classDiagram
Requirements tracing	requirementDiagram

Authoring Conventions

---
title: Descriptive Title Here
---
sequenceDiagram
    actor Client
    participant API
    Client->>API: POST /resource
    API-->>Client: 201 Created

• Always add title: in the frontmatter
• Use descriptive node IDs: AuthService not A
• One concern per diagram — split by layer (C4 context → containers → components)
• Wrap in ```mermaid fenced blocks inside .md files

Validation (mandatory per rules/mermaid.md)

# Validate syntax — catches errors before commit
npx -y @mermaid-js/mermaid-cli -i docs/architecture/schema/erd.md -o /tmp/check.svg -q
echo $? # 0 = valid, non-zero = syntax error

# Validate all .md files in docs/architecture/
find docs/architecture -name "*.md" | while read f; do
    npx -y @mermaid-js/mermaid-cli -i "$f" -o /tmp/check.svg -q 2>/dev/null \
        && echo "✓ $f" || echo "✗ $f"
done

Rendering

Via mmdc CLI

# SVG (best quality, git-friendly)
npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

# PNG at 2x scale
npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png -s 2

# Dark theme
npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg -t dark

# From a Markdown file (renders all ```mermaid blocks → diagram-N.svg)
npx -y @mermaid-js/mermaid-cli -i docs/architecture/SYSTEM.md -o /tmp/system.svg

Via mermaid.live (shareable URL for PR review)

import zlib, base64, json

def mermaid_live_url(code: str) -> str:
    state = json.dumps({"code": code, "mermaid": {"theme": "default"}})
    c = zlib.compressobj(zlib.Z_DEFAULT_COMPRESSION, zlib.DEFLATED, -15)
    enc = base64.urlsafe_b64encode(c.compress(state.encode()) + c.flush()).decode().rstrip("=")
    return f"https://mermaid.live/edit#pako:{enc}"

Interactive & editable diagrams (Excalidraw)

When a diagram must be visual and editable — dragged, restyled per element, or exported as a committable .excalidraw / PNG / SVG — hand the Mermaid you authored here to the excalidraw-diagrams skill. Its create_from_mermaid bridge converts flowchart/graph into native, editable shapes (not a locked image), and it covers the full Excalidraw MCP: per-element CRUD, layout, the describe_scene / get_canvas_screenshot verify loop, the Mermaid-fidelity table, and export_scene. The Mermaid stays the reviewable source of truth; the .excalidraw is the presentation artifact.

Integration with docs/architecture/ (crew conventions)

Artifact	Diagram type	Used by
SYSTEM.md	C4Context	All crew
schema/erd.md	erDiagram	Atlas, Ada
flows/*.md	sequenceDiagram, stateDiagram-v2	All crew
infra/topology.md	C4Container or graph TD	Hawke
frontend/flows.md	flowchart, journey	Nova
adr/*.md	Inline per ADR	Archie

Pitfalls

1. mmdc needs Puppeteer/Chromium — first run downloads ~170MB. Use Docker to avoid: docker run --rm -v "$(pwd)":/data minlag/mermaid-cli -i /data/diagram.mmd -o /data/diagram.svg
2. .md input renders all mermaid blocks — output becomes diagram-0.svg, diagram-1.svg, etc.
3. C4 diagrams — may need %%{init: {'theme': 'default'}}%% at the top if nodes don't render in some viewers
4. Node IDs with spaces — quote them: "API Gateway" not API Gateway
5. GitHub renders Mermaid natively — no need to commit rendered images for PR review; embed source in .md files