Originally published on Medium: The C4 Model — A convenient and efficient way to visualise Software Architecture
Documenting software architecture diagrams is a fundamental step in designing software. The process you follow should be, at minimum:
- Convenient: documentation shouldn’t feel like “a project in your head”. You should be able to start quickly without getting stuck on visual design.
- Efficient: ease-of-use shouldn’t degrade meaning. The diagram should still be self-sufficient and complete enough to communicate the architecture.
The C4 model (proposed by Simon Brown) addresses both by using progressive levels of abstraction: keep complexity out of the higher-level diagrams, and introduce it only as you zoom in.
The 4 levels
Context
Start with a single diagram that outlines the ecosystem your system lives in: adjacent systems, users, and integration touch points. The arrows should describe usage/integrations.
Container
Next, for each software system in the context diagram, create a container diagram. A “container” here is a deployable unit (in a microservices world, this might literally be a Docker container) or a datastore.
Component
Each container is made of components (modules). For each container, create a component diagram showing the major modules and relationships. (For example: controllers, services, and DAO layers in a Spring Boot app.)
Code
Optional. Code-level diagrams can explain components using UML, but many systems don’t need to go this deep for architecture documentation.
Example (food delivery system)
In the original Medium post, I include example diagrams for Context, Container, and Component to illustrate how you can apply the model to a multi-platform food delivery app with backend microservices.
Because Medium’s embedded images don’t always export cleanly into static Markdown, I’m linking the original post above so you can view the diagrams in-place.
Points to note
- Arrow direction doesn’t matter as long as the label makes sense in context.
- At every level, keep the connecting element from the previous diagram so you preserve context.