The C4 Model Explained
The C4 model is a hierarchical approach to software architecture diagramming created by Simon Brown. It defines four levels of abstraction — System Context, Container, Component, and Code — each providing a different zoom level for communicating architecture to different audiences. The "C4" stands for these four levels: Context, Containers, Components, and Code.
Why It Matters
Architecture diagrams are the primary visual communication tool for software structure, yet most architecture diagrams are ad hoc — drawn in inconsistent styles, at unclear abstraction levels, with ambiguous notation. The C4 model solves this by providing a standardized set of abstraction levels that map to how people actually think about software.
System Context diagrams show how the software fits into the world — what users and external systems interact with it. Container diagrams show the major deployable units — web apps, APIs, databases, message queues. Component diagrams show the internal structure of a single container — services, controllers, repositories. Code diagrams show the class or module-level structure within a component.
This hierarchy ensures that every audience gets the right level of detail. Executives see System Context. Architects see Container and Component. Developers see Component and Code. The levels are connected — you can "zoom in" from any element at one level to see its internal structure at the next level.
How It Works
C4 diagrams are generated from structural analysis data by mapping extracted architectural information to the appropriate abstraction level.
System Context diagrams are constructed from entry points and external integration detection — identifying the boundary between the analyzed system and its external dependencies (third-party APIs, databases, user interfaces).
Container diagrams are constructed from service boundary detection — identifying independently deployable units based on build system configuration, Dockerfile presence, and deployment manifest analysis.
Component diagrams are constructed from the dependency graph within a single container — grouping files into logical components based on clustering analysis and directory structure.
Code diagrams are constructed from class hierarchies, function call graphs, and module relationships within a single component.
Each diagram is exported as SVG for universal rendering and can be generated in Mermaid, PlantUML, or Structurizr DSL notation for integration with existing documentation toolchains.
How Axiom Refract Addresses This
- Axiom Refract generates C4 architecture diagrams automatically in six types — system context, container, component, deployment, dynamic, and code — exported as SVGs
- The Cartographer module produces C4 diagrams from AST-parsed structural data without manual modeling input
- Diagrams are included in every scan deliverable and can be embedded in reports, presentations, and documentation