architecture-diagram

Purpose

Generates and maintains C4-model architecture diagrams in Mermaid-in-Markdown format. Diagrams live in .docs/architecture/ and are consumed by /architecture-review as input. They are text-based (diffable), render natively in GitHub, and require no external tools.

Engineer validation is required — diagrams are never auto-approved. Present them for review after generation or update.

Diagram Types

Five diagram types, each in its own .md file:

L4 (code level) is intentionally omitted — it changes too frequently to maintain and provides minimal value over reading the source code directly.

Mermaid Format Convention

Each diagram file follows this structure:

# [Diagram Type]: [Project Name]

**Last updated:** YYYY-MM-DD
**Scope:** [what this diagram covers]

## Diagram

` ` `mermaid
[diagram content]
` ` `

## Legend

[explanation of boundaries, color coding, abbreviations]

## Change Log

| Date | Change | Reason |
|------|--------|--------|
| YYYY-MM-DD | Initial generation | Created during /bootstrap |

Use appropriate Mermaid diagram types:

• System Context / Containers / Components → graph TD or graph LR
• Sequences → sequenceDiagram
• ERD → erDiagram

Placeholder notation (avoids a silent render failure). For a variable part of a label (a slug, branch, id), use guillemets: spec/«slug», «default». Do not use:

• <slug> or the entities <slug> — the > is tokenized as an arrow and breaks the sequenceDiagram parser (the whole diagram then fails to render and falls back to raw text).
• {slug} — { starts a diamond node in graph/flowchart, so it breaks those.