Here are the key takeaways from Simon Brown’s talk on the C4 Model at Agile on the Beach 2019.
1. The Problem with Ad-hoc Diagrams
Most software architecture diagrams are confusing and inconsistent. They often consist of arbitrary boxes and lines with no clear meaning. This makes communication among team members difficult. Software teams need a shared and ubiquitous language for their architecture.
2. Abstraction First, Notation Second
The C4 model prioritizes clear levels of abstraction over a specific notation like UML. You can think of it as Google Maps for your code. You can zoom in and out depending on the level of detail you need and your target audience.
3. The Four Levels of the C4 Model
System Context The highest level shows the software system you are building and how it fits into the world around it. This includes the users and the external systems it interacts with. This overview is ideal for non-technical stakeholders.
Containers Zooming in one level reveals the containers. A container represents a separately deployable application or a data store. Examples include a web application, a mobile app, or a database. This level outlines high-level technical decisions and deployment boundaries.
Components Zooming into a specific container shows the internal building blocks. It details how the container is structured and what responsibilities each component handles.
Code The lowest and most detailed level represents the actual implementation. This is often shown through concrete class diagrams or entity-relationship diagrams. This level is highly detailed and is best generated directly from the source code.
| Level | Scope | Primary Audience | Focus |
|---|---|---|---|
| System Context | A single software system. | Non-technical and technical stakeholders. | People and external systems rather than specific technologies. |
| Containers | Applications and data stores within a single software system. | Software developers and technical support staff. | High-level technical choices and distinct deployment boundaries. |
| Components | Modules and internal structures within a single container. | Software developers and architects. | Internal architecture and code organization. |
| Code | Classes, interfaces, and objects within a single component. | Software developers implementing the system. | Specific implementation details. |
4. Alignment with the Source Code
Architecture diagrams must reflect the actual implementation. Diagrams that drift away from the codebase become obsolete and misleading. It is highly recommended to use tooling to generate these diagrams directly from the original code. This ensures a single source of truth and keeps the documentation accurate.
5. Clear Visual Communication
Every visual element in a diagram must have a clear purpose. Shapes, colors, and line types should be explicitly defined in a legend. The text inside the boxes should be descriptive and clearly state the responsibility of that specific element.