visualization
C4 Model: Visualize Software Architecture
The C4 Model provides a hierarchical approach to software architecture diagrams with four levels of abstraction: Context, Container, Component, and Code.
C4 Model: Visualize Software Architecture
TL;DR
The C4 Model is a hierarchical approach to software architecture diagrams created by Simon Brown. It uses four levels of abstraction—Context, Container, Component, and Code—to communicate architecture at different levels of detail for different audiences. Think of it as "Google Maps for your code."
Key Takeaways
- Four levels: Each level zooms in with more detail (like a map)
- Audience-appropriate: Different diagrams for different stakeholders
- Notation-agnostic: Focus on concepts, not drawing tools
- Developer-friendly: Simpler than UML, easy to learn
- Supplementary diagrams: Add deployment, dynamic, and landscape diagrams as needed
Why C4 Model Matters
Traditional architecture diagrams suffer from common problems:
- Box-and-line hell: Unclear what boxes and lines mean
- One-size-fits-all: Same diagram for executives and developers
- Outdated: Diagrams don't match the code
- Inconsistent: Different notation across teams
The C4 Model solves these by providing:
- Clear, consistent abstractions
- Multiple zoom levels for different audiences
- Simple enough to keep updated
- Diagrams as code (optional, via tools like Structurizr)
The Google Maps Analogy
Just like Google Maps shows different views at different zoom levels (world → country → city → street), C4 shows different views of your software at different abstraction levels.
The Four C's
Level 1: CONTEXT
│ "What is the big picture?"
│ Audience: Everyone (including non-technical)
│
▼
Level 2: CONTAINER
│ "What are the major building blocks?"
│ Audience: Technical people (architects, developers)
│
▼
Level 3: COMPONENT
│ "What are the major structural components?"
│ Audience: Architects, senior developers
│
▼
Level 4: CODE
"How is each component implemented?"
Audience: Developers (optional—use IDE instead)
Level 1: System Context Diagram
Purpose: Show how your system fits into the world around it.
Audience: Everyone—technical and non-technical stakeholders.
Shows:
- Your software system (as a single box)
- Users/actors who interact with it
- External systems it integrates with
- High-level relationships
Does NOT show:
- Internal structure
- Technologies used
- Detailed data flows
Key Elements:
- Customer & Administrator: Primary user personas (dark blue)
- E-Commerce System: Our software system - the focus (blue)
- Payment Gateway, Inventory, Email, Analytics: External systems (gray)
- Relationships: Clear directional arrows showing interactions
Context Diagram Guidelines
| Do | Don't |
|---|---|
| Keep it simple (5-10 elements max) | Show internal structure |
| Use natural language labels | Use technical jargon |
| Show the most important relationships | Show every integration |
| Make the scope clear | Assume knowledge |
Level 2: Container Diagram
Purpose: Show the high-level technology choices and how containers communicate.
Audience: Technical people—architects, developers, operations.
What is a "Container"? A container is a separately deployable/runnable unit that executes code or stores data:
- Web application
- Mobile app
- API/service
- Database
- File system
- Message queue
- Serverless function
Container Diagram Guidelines
| Do | Don't |
|---|---|
| Show all containers | Show internal components |
| Include technology choices | Show all classes/functions |
| Show communication protocols | Include trivial relationships |
| Keep layout clear | Overcrowd the diagram |
Level 3: Component Diagram
Purpose: Show how a container is made up of components and their interactions.
Audience: Architects and developers working on that container.
What is a "Component"? A component is a grouping of related functionality behind a well-defined interface:
- Controllers
- Services
- Repositories
- Modules
- Packages
Component Diagram Guidelines
| Do | Don't |
|---|---|
| Focus on one container | Show every class |
| Show key components only | Include implementation details |
| Indicate interfaces | Over-engineer the diagram |
| Show external dependencies | Duplicate container diagram info |
Level 4: Code Diagram
Purpose: Show how a component is implemented at the code level.
Audience: Developers working on that specific component.
Reality Check: Most teams skip this level and use their IDE instead. Only create code diagrams when:
- Explaining complex algorithms
- Onboarding new team members
- Documenting critical/complex components
When to Skip Level 4
If your code is well-structured and your IDE provides good navigation, Level 4 diagrams add more maintenance burden than value. Use UML class diagrams only when they genuinely help communication.
Supplementary Diagrams
Beyond the four core levels, C4 supports additional diagram types:
System Landscape Diagram
Purpose: Show all systems in an enterprise and their relationships.
┌─────────────────────────────────────────────────────────┐
│ Enterprise Landscape │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ CRM │ │ ERP │ │E-Comm │ │ Data │ │
│ │ System │◄─┤ System │◄─┤ System │──┤Warehouse│ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴────────────┴────────────┘ │
│ │ │
│ ┌─────▼─────┐ │
│ │Integration│ │
│ │ Platform │ │
│ └───────────┘ │
└─────────────────────────────────────────────────────────┘
Deployment Diagram
Purpose: Show how containers map to infrastructure.
┌─────────────────── AWS Region: us-east-1 ───────────────────┐
│ ┌────────────────── VPC ──────────────────────┐ │
│ │ ┌─────────── Public Subnet ───────────┐ │ │
│ │ │ ┌─────────┐ ┌─────────┐ │ │ │
│ │ │ │ ALB │ │ NAT │ │ │ │
│ │ │ └────┬────┘ └─────────┘ │ │ │
│ │ └───────┼─────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────┼──── Private Subnet ─────────┐ │ │
│ │ │ ┌────▼────┐ ┌─────────┐ │ │ │
│ │ │ │ ECS │ │ RDS │ │ │ │
│ │ │ │ Cluster │ │PostgreSQL│ │ │ │
│ │ │ └─────────┘ └─────────┘ │ │ │
│ │ └──────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
Dynamic Diagram
Purpose: Show how containers/components collaborate at runtime.
Customer Web App API Gateway Order Svc Payment Svc DB
│ │ │ │ │ │
│──Browse──►│ │ │ │ │
│ │──Products──►│ │ │ │
│ │◄──List──────│ │ │ │
│◄─Display─┤ │ │ │ │
│ │ │ │ │ │
│──Order───►│ │ │ │ │
│ │───Create────► │ │ │
│ │ │──Validate───►│ │ │
│ │ │ │──Charge──────►│ │
│ │ │ │◄──Success────┤ │
│ │ │ │──────Save────►│ │
│ │ │◄─Confirmed──┤ │ │
│ │◄──Success──┤ │ │ │
│◄─Confirm─┤ │ │ │ │
C4 Notation
Core Elements
| Element | Symbol | Description |
|---|---|---|
| Person | Stick figure or rounded box | A user or persona |
| Software System | Box | Top-level system boundary |
| Container | Box with technology | Deployable unit |
| Component | Box | Grouping of code |
| Relationship | Arrow with label | Interaction/dependency |
Best Practices
- Every element needs a name and description
- Every relationship needs a label (verb phrase describing the interaction)
- Show technology choices on containers
- Use consistent colors (but don't rely on color alone)
- Include a legend if using custom notation
Common Mistakes
- Missing descriptions: "Web App" tells nothing; "React SPA for customer shopping experience" tells everything
- Unlabeled arrows: Lines without labels are meaningless
- Wrong abstraction level: Showing classes on a Container diagram
- Too much detail: More than 10-15 elements per diagram
Tools for C4 Diagrams
| Tool | Type | Notes |
|---|---|---|
| Structurizr | Diagrams as Code | Simon Brown's tool, DSL-based |
| C4-PlantUML | Diagrams as Code | PlantUML extension |
| Mermaid C4 | Diagrams as Code | Markdown-friendly |
| Draw.io | Manual | Free, C4 shape library |
| Lucidchart | Manual | C4 templates available |
| Archi | Manual | Also supports ArchiMate |
Related Topics
- Prerequisites: What is Enterprise Architecture?
- Level Details: Context Diagram, Container Diagram
- Alternatives: ArchiMate, UML for Architecture
Quick Reference Card
C4 Model at a Glance
FOUR LEVELS (zoom in like a map)
├── Level 1: Context → Big picture, external systems
├── Level 2: Container → Deployable units, technologies
├── Level 3: Component → Major code groupings
└── Level 4: Code → Classes/functions (optional)
SUPPLEMENTARY DIAGRAMS
├── System Landscape → All systems in enterprise
├── Deployment → Infrastructure mapping
└── Dynamic → Runtime interactions
KEY RULES
• Every element: name + description
• Every arrow: labeled with verb phrase
• Per diagram: 10-15 elements max
• Show technology on containers
AUDIENCE BY LEVEL
Context → Everyone (including business)
Container → Technical staff
Component → Architects, senior devs
Code → Developers (use IDE instead)