Problem
Architecture diagrams are often either too vague (boxes and arrows) or too detailed (class diagrams). Stakeholders can't find the right level of detail for their decisions.
architecture-descriptionestablished · low operational burden
C4 Model
Also known as: c4, context-containers-components-code
Intent
A hierarchical notation for describing software architecture at four levels of abstraction, optimising for different audiences and decision contexts.
Forces
- •Different audiences need different detail: execs need context, devs need components
- •Diagrams rot quickly when disconnected from code
- •Notation must be lightweight enough to maintain
- •Tooling should support version control and review
Solution
✓ When to Use
- •Any architecture documentation that needs to be maintained
- •Design reviews where stakeholders have varied technical depth
- •Onboarding new team members to system structure
✗ When Not to Use
- •Throwaway prototypes or spike investigations
- •Infrastructure-only diagrams (use cloud provider notation)
- •When a single diagram level suffices
Pros
- +Shared vocabulary across roles
- +Diagrams as code = diffable, reviewable, versioned
- +Scales from system-of-systems to single service
- +Tool-agnostic — works with Mermaid, Structurizr, PlantUML
Cons
- −Learning curve for notation rules
- −Component level can become stale if not generated from code
- −Not a replacement for sequence diagrams or deployment diagrams
Cost Profile
Infrastructure
None — text-based
Operational
Low — maintain with code changes
Cognitive
Low — intuitive hierarchy
Failure Modes
Diagrams drift from reality (mitigate: generate from code, CI checks)
Over-documenting at component level for stable modules
Using C4 for concerns it doesn't address (security zones, physical deployment)
Real-World Examples
Alternatives
- UML
- ArchiMate
- informal-boxes-and-arrows
Related Patterns
- adr
- architecture-decision-record
- model-driven-documentation
Competency Domains
distribution communicationrequirements constraints