C4 diagrams
Source: the official C4 model at https://c4model.com/. Apply these rules whenever drawing, reviewing, or explaining a C4 diagram. Load the writing skill as well when the output includes prose (ADRs, docs, PR descriptions).
1. Purpose
C4 is a set of "maps of your code" at four zoom levels: Context, Containers, Components, Code. Simon Brown created it, inspired by UML and the 4+1 view model, to replace ad hoc boxes-and-lines diagrams. Typical failures it fixes: no legend, mixed abstractions, unlabelled arrows, missing technology, and vague labels such as "business logic".
C4 is notation-independent and tooling-independent. The abstractions and the rules below matter; the shapes do not.
2. Abstractions
Hierarchy: Person -> Software System -> Container -> Component -> Code. Each level zooms into one element of the level above.
| Abstraction | Definition | Examples |
|---|---|---|
| Person | A human user, actor, role, or persona of the system | Customer, Support Agent, Admin |
| Software System | Highest level of abstraction; delivers value to users. Typically owned and built by a single team. It is not a product domain, bounded context, tribe, or squad | Ticketing Platform, Payments System |
| Container | An independently runnable/deployable application or data store inside a software system | Server-side web app, SPA, desktop app, mobile app, serverless function, batch/console app, microservice API, database schema, S3/blob store, CDN, file system, shell script |
| Component | A grouping of related functionality behind a well-defined interface, inside a container. Not separately deployable: all components of a container share one process space | OrderController, PaymentService, EmailSender |
| Code | Classes, interfaces, functions, or DB tables inside a component | class OrderValidator, orders table |
Container rules (C4 FAQ)
- A C4 container is not Docker. It is a runnable/deployable application or data store, regardless of packaging.
- A server-rendered HTML app is 1 container. A server plus an SPA or mobile client is 2 containers communicating over a remote API.
- JARs, DLLs, assemblies, and modules are not containers. They organize code inside a container.
- Managed data services (S3, RDS, CDN) are containers inside your system boundary when you own or control the buckets or schemas. They are not external systems.
Component rules
- A component is not a folder, package, or JAR. It is a functional grouping with an interface.
- Components are not independently deployable. If it deploys separately, it is a container.
Adapting terminology
Teams may substitute language-idiomatic names (for example Module or Function in functional code) when they define the term explicitly in the diagram or its docs. Do not invent extra abstraction levels unless each is strictly defined.
3. Special modeling patterns
Queues and topics
- Wrong: one giant "Message Bus" container in the middle with every service attached (hub-and-spoke). It hides who produces and who consumes what.
- Option 1 (preferred): model each queue or topic as its own container (a message data store). Producers write to it, consumers read or subscribe from it.
- Option 2: for direct point-to-point coupling, omit the queue box and label the relationship
"Publishes order events via Queue orders [AMQP]". Optionally style these lines differently from HTTP calls (explain in the legend).
For example: Order API --"Publishes OrderPlaced to [Kafka]"--> [(orders topic)] --"Reads OrderPlaced from [Kafka]"--> Fulfilment Worker.
Microservices (Conway's Law rule)
- One team owns the whole software system: model each microservice as a group of containers inside that system's boundary (API container plus its own database schema container, or a single stateless Lambda container).
- Separate teams own each service: promote each independently owned service to its own Software System, each with its own System Context and Container diagrams. State queue/topic ownership explicitly across system boundaries.
4. Diagram catalog
Core static levels
| Level | Diagram | Recommended | Scope | Audience | Show / omit |
|---|---|---|---|---|---|
| 1 | System Context | Yes | 1 software system | Technical & non-technical | People and external systems around the system. Omit low-level technology and protocols |
| 2 | Container | Yes | 1 software system | Technical, ops | Major technology choices and inter-process protocols. Omit clustering, load balancers, failover |
| 3 | Component | No: only when it adds clear value, ideally automated | 1 container | Architects, developers | Components inside one container and their interactions |
| 4 | Code | No: generate on demand in the IDE | 1 component | Developers | UML class diagram or ERD |
Supporting diagrams
| Diagram | Recommended | Use |
|---|---|---|
| System Landscape | Yes, for organizations and portfolios | Enterprise or department map of all systems and people. A Context diagram without a single focus system |
| Dynamic | No: use sparingly | Complex runtime collaborations. Numbered-collaboration style or UML sequence style |
| Deployment | Yes | 1 environment (prod, staging, dev). Nested deployment nodes (physical, VM, Docker, Kubernetes, runtime) containing system/container instances, plus infrastructure nodes (DNS, load balancers, firewalls) |
Compatibility
- arc42: Context & Scope -> L1; Building Block level 1 -> L2; Building Block level 2 -> L3; Building Block level 3 -> L4.
- UML: supplement C4 with UML state, sequence, and ERD diagrams for workflows, state machines, and data models.
Scaling rule
When a diagram gets cluttered, do not cram dozens of boxes into one canvas. Split at the same abstraction level by business area, bounded context, feature, or single-service focus (the focus service plus its inbound and outbound neighbors).
5. Notation rules
Diagram
- Title states diagram type and scope:
Container diagram for Checkout System. - Always include a key/legend explaining shapes, colors, borders, line types, arrowheads, and acronyms.
- Keep strict abstraction purity: never mix abstraction levels (for example, no
Componentboxes inside an L2 Container diagram), and never put protocols or internal implementation steps ([HTTPS],masked packet,tool_runner) inside an L1 System Context diagram. - When comparing competing or historical architectures, label boundary titles explicitly (
Option A (Superseded)vs.Option B (Current)) and update all diagrams in the document whenever requirements or assumptions change.
Element
- Name, explicit element type (
Person,Software System,Container,Component,Database,Deployment Node), and a concise responsibility description. - Explicit technology on every container, component, and deployment node.
Relationship
- Unidirectional arrows only. Never
<-->. If data flows both ways, show the initiator's direction and describe the response in the label. - Specific active verb labels. Never a bare "Uses". Write
Submits orders to,Reads seat map from. - Protocol/technology on container-to-container relationships:
[JSON/HTTPS],[SQL],[gRPC],[AMQP].
6. Mermaid in Markdown
Default to flowchart (flowchart TB or LR), not Mermaid's native C4Context/C4Container. The native C4 syntax is experimental and often fails to render in Markdown viewers. Emit it only if the user explicitly asks and confirms renderer support.
Flowchart conventions:
subgraphfor the system boundary (Containers/Components) or deployment nodes.[(...)]for databases, data stores, queues, and topics.- Quoted HTML labels:
"<b>Name</b><br/>«Container: Tech»<br/>Short responsibility". - Arrows with quoted labels:
A -->|"Action [Protocol]"| B. - One
classDefper element type, applied consistently. - A compact
Legendsubgraph (unconnected nodes, anchored at the bottom with an invisiblebottomNode ~~~ Legendlink when Dagre places it at the top) is required whenever colors, cylinder shapes, or multiple line styles are used; place a title as the heading orTitle: ...line directly above the code block. - Dynamic diagrams:
sequenceDiagram, or aflowchartwith numbered arrow labels (1. Submits order [JSON/HTTPS]). - Deployment diagrams: nested
subgraphs in aflowchart. - Always quote labels containing parentheses, brackets, or colons.
- Never put unescaped semicolons (
;) insidesequenceDiagramorstateDiagram-v2labels (Mermaid treats;as a statement terminator and splits the remaining text into bogus states or parse errors); wrap longNoteblocks insequenceDiagramwith<br/>so text never clips at the viewport edge.
Template: L1 System Context
Title: System Context diagram for Ticketing Platform
flowchart TB
customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
ticketing["<b>Ticketing Platform</b><br/>«Software System»<br/>Lets customers browse events and buy tickets"]
payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]
email["<b>Email Service</b><br/>«Software System, external»<br/>Delivers confirmation emails"]
customer -->|"Browses events and buys tickets using"| ticketing
ticketing -->|"Requests card charges from"| payments
ticketing -->|"Sends confirmation emails using"| email
email -->|"Delivers confirmation emails to"| customer
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef system fill:#1168bd,stroke:#0b4884,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class ticketing system
class payments,email external
subgraph Legend
direction LR
l1["Person"]:::person
l2["Software System (in scope)"]:::system
l3["Software System (external)"]:::external
end
Template: L2 Container (with queue container)
Title: Container diagram for Ticketing Platform
flowchart TB
customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]
subgraph boundary["Ticketing Platform [Software System]"]
spa["<b>Web App</b><br/>«Container: React SPA»<br/>Event browsing and checkout UI"]
api["<b>Order API</b><br/>«Container: Java, Spring Boot»<br/>Validates and places orders"]
db[("<b>Orders DB</b><br/>«Container: PostgreSQL»<br/>Stores orders and tickets")]
topic[("<b>orders topic</b><br/>«Container: Kafka topic»<br/>OrderPlaced events")]
worker["<b>Fulfilment Worker</b><br/>«Container: Python»<br/>Issues tickets and sends emails"]
end
customer -->|"Browses and buys using [HTTPS]"| spa
spa -->|"Submits orders to [JSON/HTTPS]"| api
api -->|"Writes orders to [SQL/TCP]"| db
api -->|"Publishes OrderPlaced to [Kafka]"| topic
worker -->|"Reads OrderPlaced from [Kafka]"| topic
worker -->|"Updates ticket status in [SQL/TCP]"| db
api -->|"Requests card charges from [JSON/HTTPS]"| payments
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef container fill:#438dd5,stroke:#2e6295,color:#fff
classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class spa,api,worker container
class db,topic store
class payments external
subgraph Legend
direction LR
l1["Person"]:::person
l2["Container"]:::container
l3[("Data store / queue / topic")]:::store
l4["External system"]:::external
end
Legend note: arrows point from the initiator to the target. The label states the action and [protocol].
Template: Deployment
Title: Deployment diagram for Ticketing Platform (Production)
flowchart TB
users["<b>Customer browser</b><br/>«Deployment Node: Chrome»"]
subgraph aws["AWS «Deployment Node: Cloud, us-east-1»"]
dns["<b>Route 53</b><br/>«Infrastructure Node: DNS»"]
lb["<b>Load Balancer</b><br/>«Infrastructure Node: ALB»"]
subgraph eks["EKS «Deployment Node: Kubernetes cluster»"]
subgraph pod["order-api pod «Deployment Node: Docker, x3»"]
api["<b>Order API</b><br/>«Container instance: Java, Spring Boot»"]
end
end
subgraph rds["RDS «Deployment Node: PostgreSQL 16»"]
db[("<b>Orders DB</b><br/>«Container instance: PostgreSQL schema»")]
end
end
users -->|"Resolves hostname using [DNS]"| dns
users -->|"Sends requests to [HTTPS]"| lb
lb -->|"Forwards requests to [HTTP]"| api
api -->|"Reads and writes orders in [SQL/TCP]"| db
Add a Legend subgraph if you use colors or styles beyond defaults.
Template: Dynamic (Sequence)
Title: Dynamic diagram (sequence style) for Order Checkout in Ticketing Platform
sequenceDiagram
autonumber
actor customer as Customer
participant spa as Web App (React SPA)
participant api as Order API (Spring Boot)
participant payments as Payment Provider
participant db as Orders DB (PostgreSQL)
participant topic as orders topic (Kafka)
customer->>spa: Clicks "Place Order"
spa->>api: POST /orders [JSON/HTTPS]
api->>payments: Charges card [JSON/HTTPS]
payments-->>api: Payment authorized
api->>db: Inserts order row [SQL/TCP]
api->>topic: Publishes OrderPlaced [Kafka]
api-->>spa: 201 Created (order confirmation)
spa-->>customer: Shows order receipt
Keep sequenceDiagram participant and message labels free of unquoted slashes, semicolons (;, which Mermaid parses as statement terminators), or raw newlines for maximum Markdown viewer compatibility.
7. Diagramming vs. modelling
Hand-drawn or hand-written diagrams drift across views. For large systems, keep one model (for example Structurizr DSL, or another directed-graph model) as the single source of truth and generate each view from it. For a handful of diagrams in a README, Mermaid by hand is fine.
8. Pre-output checklist
Check every diagram against this list (from https://c4model.com/diagrams/checklist) before presenting it:
- Every element has a name, an explicit type, a clear responsibility, and (for containers, components, and deployment nodes) a technology choice.
- Every acronym and abbreviation is explained.
- Every arrow is unidirectional (
-->, never<-->), specifically labelled, and states the protocol for inter-container calls. - Every color, shape, icon, border style, and box size is consistent and explained in a
Legendsubgraph. - Every diagram has a title stating its type and scope, keeps strict level purity (no protocols/implementation trivia in L1; no mixed Component/Container boxes), and stays in sync with any updated requirements in the surrounding document.
When reviewing someone else's diagram, report each failed item with the element or arrow concerned and a concrete fix.