The C4 Architecture Model

Architecture diagrams fail in a predictable way. Someone draws boxes and arrows on a whiteboard, labels them with component names, and calls it documentation. Three weeks later, a new team member opens the diagram and cannot determine what any of it means. The boxes have no clear scope. The arrows carry no semantic weight. Nobody agrees on what level of detail the diagram represents.

The C4 model, created by Simon Brown, solves this through a consistent hierarchy of four abstraction levels: Context, Containers, Components, and Code. Each level answers different questions, and together they give a complete picture of a system without requiring any single diagram to carry too much information.

Core Principles#

• Hierarchy over chaos: Each level adds detail while maintaining context
• Single responsibility: Every element should communicate its purpose in plain language
• Consistency: The same notation applies across all levels
• Appropriate detail: No more and no less than what is needed at each level

The Four Levels#

Level 1: Context#

The context diagram answers the most fundamental questions: what is the system, who uses it, and what does it depend on externally. It deliberately ignores implementation detail.

[External Users/Systems] <---> [Your System] <---> [External Dependencies]

For a streaming service, the context diagram shows viewers, content partners, payment processors, CDN providers, and the platform itself. Nothing more.

This diagram is for everyone—developers, product managers, stakeholders. Its value is clarity, not completeness.

Level 2: Containers#

In C4, a container is any independently deployable unit that makes up the system: a web application, an API server, a database, a message queue. The container diagram shows these units, their responsibilities, their technology choices, and how they communicate.

+-------------------+     +------------------+     +------------------+
|  Single-Page App  | --> |  API Gateway     | --> |  Message Queue   |
|  (React/Next.js)  |     |  (Node.js)       |     |  (RabbitMQ)      |
+-------------------+     +------------------+     +------------------+
                               |
                               v
                    +----------------------+
                    |  PostgreSQL Cluster  |
                    |  (User/Order Data)   |
                    +----------------------+

This diagram is primarily for developers and architects. It answers the question: what needs to be running for the system to work?

Level 3: Components#

The component diagram zooms into a single container and shows its internal structure: services, repositories, managers, and the dependencies between them.

+-------------------------+    +----------------------+
|  Authentication Service |    | Rate Limiter         |
| - JWT validation        |    | - Request tracking   |
| - Role management       |    | - Quota enforcement  |
+-------------------------+    +----------------------+
            |                           |
            v                           v
    +------------------+        +-----------------+
    | Request Router   | -----> | Cache Manager   |
    | - API versioning |        | - Redis cache   |
    | - Load balancing |        | - TTL policies  |
    +------------------+        +-----------------+

This is used primarily during design and onboarding. It explains how a container is organized internally.

Level 4: Code#

Code-level diagrams are not created for the entire codebase. They are reserved for complex algorithms, critical business logic, and integration points that require explicit documentation. Use them selectively—during design reviews, for public API documentation, or to explain a non-obvious workflow.

Practical Tips#

Getting started

1. Start with the context diagram. Always.
2. Use simple tools first—pen and paper is fine for the first draft.
3. Get feedback from both technical and non-technical stakeholders before refining.

Common mistakes

• Mixing abstraction levels within a single diagram
• Adding detail that only the author understands
• Using technical jargon in a context diagram intended for a non-technical audience
• Treating the diagrams as static artifacts rather than living documentation

Tools

• Structurizr (purpose-built for C4)
• PlantUML with C4 extensions
• draw.io with C4 templates
• Mermaid (for simpler diagrams)

Applied Example: E-Commerce Platform#

Context: The system interacts with customers, vendors, payment providers, and shipping services.

Containers: Customer-facing web app, vendor portal, order management service, inventory service, payment service, per-service databases.

Components (within the Order Management Service): order validator, pricing engine, inventory checker, notification dispatcher, payment coordinator.

Code (within the Pricing Engine): price calculation, discount rules, tax calculators, currency converters.

When C4 Adds the Most Value#

• System documentation: Creating diagrams that are actually consulted rather than archived.
• Architecture decisions: Making design choices visible and reviewable.
• Onboarding: Getting new engineers productive without requiring a full walkthrough.
• Stakeholder communication: Explaining technical decisions to non-technical audiences without oversimplification.

Conclusion#

The C4 model works because it imposes discipline on what a diagram is allowed to show. Each diagram has a clear purpose, a defined audience, and a consistent level of abstraction. That constraint is not a limitation—it is what makes the diagrams useful.

Start with the context level. Document only what matters. Let the diagrams evolve alongside the system.

Simon Brown's official documentation is available at c4model.com.