C4 Model

The C4 Model, created by Simon Brown, provides a hierarchical set of four diagram types for visualizing software architecture at different levels of abstraction, inspired by how map zoom levels serve different navigation needs. The four levels are: Context (system and its users/external systems), Container (deployable units: apps, databases, microservices), Component (logical building blocks within a container), and Code (class/module level, only for complex components). C4 succeeds where UML struggles because each level has a clear, fixed purpose — junior engineers draw Components where seniors draw Containers, because C4 makes the zoom level explicit.

Key Points

• Level 1 — System Context: one box for "your system", surrounding boxes for users and external systems it integrates with — enough for a 5-minute stakeholder briefing.
• Level 2 — Container: "what runs where" — each separately deployable unit (React SPA, Node.js API, PostgreSQL, Redis, Kafka) is a box; communication is an arrow with technology and protocol labeled.
• Level 3 — Component: decompose one container into its logical components (Controllers, Services, Repositories) — useful for onboarding new engineers to a specific service.
• Level 4 — Code: class diagrams within a component — rarely worth the maintenance cost for most codebases; generate from code using IDE plugins rather than maintaining manually.
• C4 notation rules: every element has a name, type, and short description; every relationship has a description and technology annotation; colour-codes distinguish element types.
• C4 vs. UML: C4 constrains the zoom level explicitly, preventing the common mistake of mixing system context and code-level details on the same diagram.
• Structurizr (by Simon Brown) allows C4 diagrams as code using a DSL — store architecture definitions in git alongside code for version-controlled, reviewable architecture.
• C4 can be extended with Deployment Diagrams (mapping containers to infrastructure) and Dynamic Diagrams (sequence of interactions for a specific scenario) — these are official C4 supplementary diagrams.