02.01 · C4 Model Deep Dive

Level: Practitioner Pre-reading: 02 · Architecture Diagramming

The C4 Model (created by Simon Brown) is a hierarchical approach to diagramming software architecture. It gives teams a shared vocabulary and a set of abstraction levels that match different audiences.

Why C4 Exists

Before C4, architecture diagrams were informal box-and-arrow drawings with no consistent meaning. A box might be a service, a database, a team, or a physical server — with no way to tell. C4 solves this by defining a small, consistent vocabulary and four abstraction levels.

The key insight

C4 doesn't prescribe a drawing tool or a notation standard — it prescribes a thinking model: "Zoom in and out deliberately, and always be explicit about what your diagram represents."

The Four Levels

graph TD L1["Level 1 — System Context\nThe system and its relationships\nto users and external systems"] L2["Level 2 — Container\nDeployable units inside the system\n(web apps, APIs, databases, queues)"] L3["Level 3 — Component\nLogical groupings inside one container\n(controllers, services, repos)"] L4["Level 4 — Code\nClasses, functions — rarely drawn by hand"] L1 --> L2 --> L3 --> L4 style L1 fill:#1976D2,color:#fff style L2 fill:#388E3C,color:#fff style L3 fill:#F57C00,color:#fff style L4 fill:#616161,color:#fff

Level 1: System Context Diagram

Question it answers: "What does this system do, who uses it, and what does it depend on?"

Audience: Everyone — CTO, product manager, new engineer, external partner.

Elements

Element Visual Meaning
Person Rounded box (blue) A human user or role
Your system Box (dark) The system you are documenting
External system Box (grey) A third-party or internal system outside your scope
Relationship Arrow with label "uses", "sends data to", "receives events from"

Example — E-commerce System Context

graph TD Customer[Customer\n<Person>] Admin[Admin User\n<Person>] ECS["E-Commerce System\n<Your System>"] Payment["Payment Gateway\n<External System>\nStripe"] Email["Email Service\n<External System>\nSendGrid"] ERP["ERP System\n<External System>\nSAP"] Customer -->|"Browses, orders, pays"| ECS Admin -->|"Manages products, orders"| ECS ECS -->|"Processes payments via"| Payment ECS -->|"Sends transactional email via"| Email ECS -->|"Syncs inventory with"| ERP

Level 2: Container Diagram

Question it answers: "What are the deployable/runnable pieces and how do they communicate?"

Audience: Architects, senior engineers, DevOps.

A container in C4 is not a Docker container — it is any independently deployable or runnable unit: a web app, a mobile app, an API, a database, a message queue, a serverless function.

Example — E-commerce Containers

graph TD Customer[Customer\n<Person>] Admin[Admin\n<Person>] subgraph "E-Commerce System" WebApp["Web App\n<Container: React SPA>\nDelivered via CDN"] API["API Server\n<Container: Node.js>\nREST / GraphQL"] DB[("Orders DB\n<Container: PostgreSQL>")] Cache["Cache\n<Container: Redis>"] Queue["Message Queue\n<Container: RabbitMQ>"] Worker["Background Worker\n<Container: Node.js>\nProcesses async jobs"] end Payment["Payment Gateway\n<External System>"] Email["Email Service\n<External System>"] Customer -->|"HTTPS"| WebApp Admin -->|"HTTPS"| WebApp WebApp -->|"API calls via HTTPS"| API API -->|"Reads/writes"| DB API -->|"Caches sessions"| Cache API -->|"Publishes order events"| Queue Queue -->|"Consumes"| Worker API -->|"Charges card via"| Payment Worker -->|"Sends email via"| Email

Level 3: Component Diagram

Question it answers: "What are the logical components inside this container?"

Audience: Developers working on that specific container.

Don't draw L3 for every container

Only draw L3 for containers that are complex enough to benefit from it. A simple CRUD API with 3 endpoints does not need a component diagram.

Example — API Server Components

graph TD WebApp["Web App\n<Container>"] subgraph "API Server (Node.js)" Router["API Router\n<Component>"] AuthMW["Auth Middleware\n<Component>\nJWT validation"] OrderCtrl["Order Controller\n<Component>"] OrderSvc["Order Service\n<Component>\nBusiness logic"] OrderRepo["Order Repository\n<Component>\nData access"] PaymentSvc["Payment Service\n<Component>\nStripe integration"] end DB[("Orders DB")] StripeAPI["Stripe API\n<External>"] WebApp --> Router Router --> AuthMW --> OrderCtrl OrderCtrl --> OrderSvc OrderSvc --> OrderRepo --> DB OrderSvc --> PaymentSvc --> StripeAPI

Level 4: Code

Question it answers: "How is this component implemented at the class/function level?"

In practice, Level 4 is almost never hand-drawn. IDEs and documentation generators (e.g., Javadoc, Doxygen) generate this automatically.

When to draw Level 4

Only for genuinely complex algorithmic components where the class structure is not obvious — for example, a custom serialisation framework or a complex state machine.

C4 Notation Rules

Every C4 diagram must include:

  • [ ] Title — "System Context for E-Commerce" not just "Architecture"
  • [ ] Level label — L1 / L2 / L3 in the title or subtitle
  • [ ] Key/legend — shapes, colours, and their meanings
  • [ ] Technology labels on containers and components
  • [ ] Relationship labels — verbs describing what flows over the arrow

Supplementary Diagrams

C4 is extensible. Two common supplementary diagrams:

Diagram Purpose
System Landscape Shows multiple systems and their relationships — zoom out beyond L1
Dynamic Diagram Shows how elements collaborate for a specific use case — like a sequence diagram
Deployment Diagram Maps containers onto infrastructure (Kubernetes nodes, cloud regions, CDN)

C4 Tooling

Tool Approach
Structurizr (Simon Brown's own tool) Code-as-diagrams; single model, multiple views
draw.io / diagrams.net Manual; C4 shape library available
Mermaid Code-first; no official C4 support but approximated with flowcharts
PlantUML + C4-PlantUML Text-as-diagrams; rich C4 support
Lucidchart Manual; C4 templates available

Structurizr is the gold standard

Structurizr enforces a single architecture model from which all four views are derived — preventing inconsistencies between diagrams. It is the tool Simon Brown recommends and uses himself.