UML & C4 Model
Learn to document software architecture using the C4 model — from system context to code.
What is the C4 Model?
The C4 model was created by Simon Brown as a way to describe and communicate software architecture using a set of four hierarchical diagrams:
1. Level 1 – System Context: The big picture. Shows the system and how it fits into the world. 2. Level 2 – Container: Zooms into the system. Shows deployable/runnable units (apps, databases, services). 3. Level 3 – Component: Zooms into a container. Shows the major components and how they interact. 4. Level 4 – Code: Zooms into a component. Shows classes, interfaces, objects.
Why C4 over Traditional UML?
Traditional UML has 14 diagram types — most teams use 3-4 but inconsistently. C4 solves this by:
C4 Notation Elements
| Element | Meaning |
|---|---|
| Person | A human user or role |
| Software System | Any software system (yours or external) |
| Container | An application, database, file store, microservice |
| Component | A grouping of related functionality within a container |
Key Principle
"Abstractions first, notation second." Start with the right level of detail for your audience, then choose tools and notation.
When to Use Each Level
- Context (L1): New team members, business stakeholders, executive presentations
- Container (L2): Development teams, infrastructure planning, security reviews
- Component (L3): Senior developers, design reviews of a specific service
- Code (L4): Only if auto-generated from code — otherwise skip
Scenario
An analyst is documenting the architecture of an e-commerce platform for a new engineering team.
---
Level 1: System Context Diagram
[Customer] --uses--> [Online Store] --sends emails via--> [SendGrid]
[Admin] --uses--> [Online Store] --processes payments via--> [Stripe]
--stores data in--> [Analytics Platform]Textual description:
---
Level 2: Container Diagram (inside Online Store)
[React SPA] --API calls--> [API Server (FastAPI)]
[Mobile App] --API calls--> [API Server]
| |
[PostgreSQL] [Redis Cache]
|
[Background Worker]
(Celery + RabbitMQ)Containers:
---
Level 3: Component Diagram (inside API Server)
[Auth Component] ← JWT validation, login/register [Product Component] ← catalog, search, inventory [Order Component] ← cart, checkout, order lifecycle [Payment Component] ← Stripe integration, webhooks [Notification Component] ← triggers emails via SendGrid
Each component has its own router, service, and repository layer.
---
Key Insight
The C4 diagrams became the onboarding document for the new team. Engineers could drill down from the business-level context all the way to the specific component they were responsible for — without reading 200 pages of wiki.
Level 2 — Container Diagram
What is a Container?
A container is a separately deployable/runnable unit. Examples:
Key questions to answer on a Container diagram: 1. What are the high-level technology choices? 2. How do containers communicate? (HTTP, gRPC, AMQP, WebSocket) 3. Where is data stored and by what?
Common Mistakes:
---
Level 3 — Component Diagram
What is a Component?
A component is a grouping of related functionality behind a well-defined interface. In code, this often maps to:
Key questions for Level 3: 1. What components are inside this container? 2. What are the responsibilities of each component? 3. How do they interact with each other and with external systems?
When to create a Component diagram:
When to skip it: