c4-diagramming

C4 Diagramming

C4 Model for structural architecture visualization. Produces diagrams at four zoom levels, mapped into the artifact pyramid.

C4-to-Pyramid Mapping

C4 Level	Pyramid Layer	Path
Level 1: System Context	L1 (Summary)	01-summary/system-context.md
Level 2: Container	L2 (Analysis)	02-analysis/structural-views/container.md
Level 3: Component	L2 (Analysis)	02-analysis/structural-views/components.md
Level 4: Code	L3 (Dossiers)	03-dossiers/code-level-detail.md

C4 is the cleanest structural fit — its four-level hierarchy maps to the three pyramid layers with almost no translation, and Levels 2-3 both resolve to separate L2 analysis files.

Authoring Formats

Mermaid (Default for Quick Diagrams)

Use when you need a single diagram embedded in markdown. See the GitHub Rendering Constraint section below for C4-in-Mermaid compatibility notes.

Structurizr DSL (Recommended for Long-Lived Projects)

Structurizr DSL is the C4 model's reference "models as code" implementation, created by Simon Brown. Define the entire architecture model in a single DSL file; all 4 C4 levels are generated from it. This ensures structural consistency across diagrams that hand-written Mermaid cannot guarantee.

workspace {
    model {
        user = person "Customer"
        system = softwareSystem "Your System" {
            webapp = container "Web Application" "TypeScript, React"
            api = container "API" "Go"
            db = container "Database" "PostgreSQL"
            user -> webapp "Uses"
            webapp -> api "Makes API calls"
            api -> db "Reads/writes"
        }
    }
    views {
        systemContext system { include * autolayout lr }
        container system { include * autolayout lr }
        component api { include * autolayout lr }
        theme default
    }
}

Key capabilities:

• !adrs docs/adr — imports Architecture Decision Records (adr-tools, MADR, log4brains) into the workspace, rendered alongside C4 diagrams
• !docs docs/arc42 — imports arc42 documentation as Markdown/AsciiDoc
• Structurizr Lite (Docker) — local preview at http://localhost:8081
• CI commands: validate, inspect, export (PlantUML, Mermaid, static site)