C4 Model

framework · computer science · organizing-schema

Brown's hierarchical software architecture diagrams: Context, Container, Component, Code.

The C4 Model was developed by Simon Brown beginning around 2006 and presented systematically through Brown's book Software Architecture for Developers and the c4model.com reference. The model articulates four levels of architectural diagrams at progressively finer granularity, each with its own audience and concerns. Level 1 (System Context) shows the system as a single box with users, external systems, and high-level interactions — the audience is everyone (technical and non-technical). Level 2 (Container) decomposes the system into containers (applications, data stores, microservices, single-page apps) and their interactions — the audience is technical staff. Level 3 (Component) decomposes a single container into its major components and their interactions — the audience is developers. Level 4 (Code) shows code-level details (UML class diagrams or equivalent) for a single component — typically auto-generated rather than hand-drawn. The model deliberately positions itself against UML's complexity, providing a small set of diagram types that cover the most common architectural-communication needs without the formality that has limited UML adoption. Tooling support includes Structurizr (Brown's own), PlantUML extensions, and Mermaid.

Originators

Simon Brown high

Year / Decade

Mid-2000s development; ongoing publication via c4model.com high

Primary sources

Brown, S. (ongoing). The C4 Model for Visualising Software Architecture (c4model.com), Brown, S. (2014, multiple editions). Software Architecture for Developers (Leanpub) high

Core components

Four levels: 1. System Context, 2. Container, 3. Component, 4. Code
Supplementary diagrams: System Landscape, Dynamic, Deployment
Notation conventions: persons, software systems, containers, components
Container as 'separately runnable/deployable unit'
Distinction from UML by minimalism
Tooling support (Structurizr, PlantUML C4, Mermaid)

Primary use case

Software architecture documentation and communication; alternative to UML for most application-architecture documentation needs; basis for architecture review and onboarding documentation; integration with diagrams-as-code workflows; foundation for many architecture-decision-record practices; common reference in modern architecture education.

Common criticisms

Definition of 'container' is genuinely confusing — overlaps but doesn't match Docker container terminology, leading to vocabulary collision
level boundaries can be ambiguous in microservices systems where containers and components overlap
Level 4 (code) is rarely used in practice as code-as-source-of-truth makes hand-drawn class diagrams obsolete
doesn't address dynamic behavior, security boundaries, or data flow as cleanly as static structure
'just architecture' framing misses cross-cutting concerns like observability, security, and reliability that modern systems require explicit architectural treatment
commercial Structurizr tooling has shaped adoption in ways that not all teams want to follow.

Lineage

Siblings: 4+1 Architectural Views