| name | c4-model |
| description | Interactively co-build a software architecture using Simon Brown's C4 model (Context, Container, Component, Code). The skill detects the usage mode (greenfield design, retro-documenting from code or prose, review/explanation, update), runs a structured framing dialogue, proposes incremental drafts, and iterates until explicit user validation. Output format is negotiated (default Mermaid C4 + Markdown; alternatives Structurizr DSL, PlantUML, images). Destination is negotiated too: local filesystem by default, or connected MCP (Notion, Google Drive, Linear documents…). Use this skill whenever the user asks for a C4 diagram, modèle C4, architecture diagram, container diagram, system context, diagramme d'architecture, wants to brainstorm/design a system architecture, shares code or prose wanting it documented, or wants to review/update an existing C4. Trigger proactively whenever an architecture overview or system documentation would clearly help — even without an explicit "C4" mention. |
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.
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:
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:
- 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/.
Pre-delivery checklist
Before any delivery, run through 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 Code uses classDiagram (classical UML).
Complete, authoritative reference: mermaid-c4-syntax.md (exhaustive signatures, nested boundaries, styles, directions, Context/Dynamic/Deployment examples, unsupported features).
Essential elements
# Actors and systems
Person(alias, "Label", "Description")
Person_Ext(alias, "Label", "Description")
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")
SystemDb(alias, "Label", "Description")
SystemQueue(alias, "Label", "Description")
# Containers (level 2)
Container(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
ContainerQueue(alias, "Label", "Technology", "Description")
# Components (level 3)
Component(alias, "Label", "Technology", "Description")
# Boundaries
Enterprise_Boundary(alias, "Enterprise") { ... } # at the Context level
System_Boundary(alias, "System") { ... } # at the Container level
Container_Boundary(alias, "Container") { ... } # at the Component level
# Relationships
Rel(from, to, "Intent label", "Technology/Protocol")
Rel_U / Rel_D / Rel_L / Rel_R # direction hints
Reference example — Container diagram
C4Container
title Container diagram for Internet Banking System
Person(customer, "Banking Customer", "A customer of the bank.")
System_Boundary(banking, "Internet Banking System") {
Container(spa, "Single-Page App", "JavaScript, Angular", "Provides all of the Internet banking functionality to customers via their web browser.")
Container(mobile, "Mobile App", "Xamarin", "Provides a limited subset of the Internet banking functionality to customers via their mobile device.")
Container(api, "API Application", "Java, Docker Container", "Provides Internet banking functionality via a JSON/HTTPS API.")
ContainerDb(db, "Database", "Oracle Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
}
System_Ext(mail_system, "E-mail System", "The internal Microsoft Exchange e-mail system.")
System_Ext(mainframe, "Mainframe Banking System", "Stores all of the core banking information.")
Rel(customer, spa, "Views account balances, makes payments using")
Rel(customer, mobile, "Views account balances, makes payments using")
Rel(spa, api, "Makes API calls to", "JSON/HTTPS")
Rel(mobile, api, "Makes API calls to", "JSON/HTTPS")
Rel(api, db, "Reads from and writes to", "JDBC")
Rel(api, mail_system, "Sends e-mail using", "SMTP")
Rel(api, mainframe, "Makes API calls to", "XML/HTTPS")
Level 4 — Code (UML)
Mermaid has no native C4Code type. Use classDiagram — consistent with C4 practice.
classDiagram
class SignInController {
-SecurityComponent security
+signIn(username, password)
}
class SecurityComponent {
-UserRepository users
+authenticate(username, password) User
}
SignInController --> SecurityComponent
Common pitfalls to avoid
- Skipping mode detection — producing a diagram without knowing whether the user wants to design, retro-document, review, or update. The right workflow depends entirely on the mode.
- Mixing abstraction levels in the same diagram (e.g. a Container next to a Component at level 2)
- Forgetting external systems at the Context level (a system never lives alone)
- Overly dense diagrams — if a Container has more than 15-20 components, it probably needs to be split
- Useless arrow labels ("Uses", "Calls") — always spell out the intent
- Container / Component confusion — a Container is a runtime/process deployable independently; a Component is a grouping inside a container
- Forgetting technology on Containers/Components — strict C4 rule
- Delivering without validation — no final write until the user has said "ok"
- Inventing to fill gaps instead of listing assumptions — any unconfirmed inference belongs in the Assumptions section
Bundled references
Documentation for the selected mode (load with Read after detection):
Cross-cutting references (consult as needed):
