c4-model

C4 model — diagramming a software architecture

Simon Brown's C4 model (c4model.com) describes a software architecture through four hierarchical levels of abstraction. This skill covers the full cycle around a C4 diagram: design, retro-documentation, review, update.

The 4 levels

| Level | Diagram | Mermaid | Zoom | Audience | |---|---|---|---|---| | 1 | Context | C4Context | System + actors / external systems | Everyone (technical and non-technical) | | 2 | Container | C4Container | Applications, services, internal data stores | Technical team (dev, ops, architecture) | | 3 | Component | C4Component | Internal components of a container | Developers of that container | | 4 | Code | classDiagram (UML) | Classes/functions of a component | Developers (often generated by the IDE) |

Simon Brown's golden rule: "Context + Container diagrams are sufficient for most software development teams." Only generate levels 3 and 4 when the user explicitly asks for them or when they bring genuine value (complex container, onboarding, high-risk zone). When in doubt, produce levels 1 and 2 and propose to go deeper.

C4 also supports supporting diagrams: System Landscape, Deployment, Dynamic. See [supporting-diagrams.md](supporting-diagrams.md).

Mode detection (router)

Always start by identifying the mode. If it's not obvious from the user's message, ask one question:

"Do you want to: (a) design a new architecture, (b) retro-document an existing system (code or prose), (c) review or explain an existing diagram, or (d) update a C4 that's already in place?"

Signals to infer without asking

| User signal | Mode | |---|---| | Path to a repo, code snippet pasted, "here's my codebase" | Document-code | | README, ADR, spec, meeting transcript pasted | Document-prose | | Diagram (Mermaid/PlantUML/Structurizr) pasted + "what is this?" / "is this good?" | Review | | Existing diagram + "add/remove/change X" | Update | | Vague idea, no artifact, "I want to design…" | Design |

File to load based on the mode

Once the mode is known, read the corresponding file with Read to apply its detailed flow:

| Mode | File | |---|---| | Design | [mode-design.md](mode-design.md) | | Document-code | [mode-document-code.md](mode-document-code.md) | | Document-prose | [mode-document-prose.md](mode-document-prose.md) | | Review | [mode-review.md](mode-review.md) | | Update | [mode-update.md](mode-update.md) | | Supporting (Landscape/Deployment/Dynamic) | [supporting-diagrams.md](supporting-diagrams.md) |

The rules in the Common contract section below apply to every mode that produces or modifies a diagram.

Common contract (all modes)

Output format

Default: one Markdown document per level, with the diagram embedded as Mermaid C4. Mermaid C4 renders in most Markdown viewers that support Mermaid — GitHub and GitLab render it natively; Obsidian supports it natively; Notion supports Mermaid with varying compatibility for C4-specific syntax; VS Code requires the Markdown Preview Mermaid Support extension. Always verify C4 rendering in the target viewer, since Mermaid marks C4 syntax as experimental.

Alternatives negotiated with the user:

• Structurizr DSL — Simon Brown's official tool; relevant when the user wants to generate multiple views from a single source
• PlantUML with the C4-PlantUML library — when the project already runs on PlantUML (syntax is near-identical to Mermaid C4)
• Image export (SVG/PNG) — to embed in a slide deck or PDF; note that the export goes through mermaid-cli on the user's side
• Markdown only without a diagram — when the target tool supports no rendering at all

Confirm the format during framing. Never assume.

Destination

Default: local filesystem, in docs/architecture/ (or another path if the user prefers). Alternatives when an MCP is connected in the session:

• Notion page — mcp__notion__* tools
• Linear document — mcp__linear__save_document
• Google Drive file — mcp__*Drive* tools
• Others (Confluence, gist…) — only when the matching MCP is actually present

List only the MCPs actually available in the session, never invent. If several are available, ask which one. Inline output (rendered in the conversation without persistence) is also valid for a quick review or exploration.

Notation rules (non-negotiable)

Rules derived from the C4 model. They apply to every diagram produced or corrected by the skill:

Diagram

• Explicit title (e.g. "Container diagram for Internet Banking System")
• A legend in the Markdown document ("Legend" section), since Mermaid C4 does not always render a key by default
• Acronyms/abbreviations explained

Elements

• Type is always explicit (Person, System, Container, Component, DB, Queue, Ext…)
• Each element has a short description of its responsibility
• Every Container and Component states its technology explicitly (e.g. "Java, Spring Boot", "PostgreSQL 15", "RabbitMQ")

Relationships

• Every arrow is unidirectional (avoid BiRel, split it into two Rels)
• Every arrow is labeled with a concrete intent — ban bare "Uses", "Calls", "Reads". Prefer "Reads account balances from", "Publishes OrderCreated events to", "Sends email notifications via"
• Inter-container relationships (typically IPC) state the protocol/technology (HTTPS/JSON, gRPC, AMQP, JDBC, SMTP…)

Deliverable per level

Invariant: never deliver a bare diagram without the document that accompanies it — the diagram must remain self-standing, but the document describes the why (context, trade-offs, assumptions). This rule holds regardless of the output format.

Default structure (local filesystem):

docs/architecture/
├── 01-context.md                            # Level 1 — always
├── 02-container.md                          # Level 2 — always
├── 03-component-<container-name>.md         # Level 3 — one per zoomed container
└── 04-code-<component-name>.md              # Level 4 — rare, on demand

On an MCP destination, granularity stays identical: one page/document per level, linked via the "Links to other levels" section of the template.

Each document follows [level-template.md](level-template.md):

• Overview
• Diagram
• Legend
• Elements (table: name, type, technology, responsibility)
• Key relationships (table: from, to, intent, protocol)
• Notable architectural decisions
• Assumptions
• Links to other levels

For filled-out examples, see [examples/](examples/).

Pre-delivery checklist

Before any delivery, run through [review-checklist.md](review-checklist.md) — Simon Brown's official checklist plus the C4-specific additions introduced by this skill.

Dialogue rules (all interactive modes)

• Max 5 questions per batch. Never drown the user in a form.
• Reformulate before assuming: "If I understand correctly, X. Is that right?"
• Offer options when the user hesitates: "Two approaches: (A) modular monolith, (B) two services. For your context [reasons], I'd lean toward B. What do you think?" Name trade-offs explicitly.
• Incremental drafts: show a partial diagram as soon as there's enough material — validate as you go rather than at the end.
• Explicit assumptions: anything that was guessed goes into the "Assumptions" section of the document, never silently baked into the diagram.
• No premature delivery: no final write to the chosen destination until the user has explicitly validated the current level.
• Universal stop criterion: the user explicitly says "ok, that's good", "finalized", "we can ship" — or an unambiguous equivalent. When in doubt, propose one more review pass rather than delivering.

Mermaid C4 syntax — essential cheatsheet

Mermaid natively supports C4Context, C4Container, C4Component, C4Dynamic, C4Deployment. Level