#31 Documenting Software Architecture using C4 Model
Software architecture is a dynamic system that evolves over time. Documenting an evolving system is a common pain point for engineers because
(A) It is time-consuming,
(B) There’s no widely adopted standard or convention,
(C) Engineers are more incentivised to ship code than to document.
And last one is unclear purpose. Some senior engineers and tech leads argue, “Who will benefit from these docs if we already have the mental model of the system?”
You can see why this single-point-of-failure is not sustainable.
However, most engineers hand-draw the architecture using simple diagrams (boxes and arrows) because it’s a more intuitive and straightforward approach. The C4 Model builds on this concept, providing some convention and clear boundaries to make the diagrams more consistent. It’s been adopted by engineering teams like Spotify (blog) and is referenced in several articles, including Martin Fowler’s: Building Infrastructure Platform.
In this post, I’ll explain what the C4 Model is and how it can be used for better team collaboration and documentation of software architecture.
Documenting Software Architecture
Designing an architecture is an evolving process, not a finished product. This holds true for different types of organisations, including startups, scale-ups, and big tech. However, the driving factors can vary. It might be a scalability issue requiring architectural changes for new read/write patterns, or a new project that demands additional infrastructure (e.g., building ML pipelines, etc.).
Keeping the architecture documentation up-to-date without a clear framework is challenging for engineers, especially when they’re busy with other tasks like project scoping and feature development.
As a byproduct of missing frameworks, we default to using many shapes (boxes, circles, etc.) with many arrows to model the systems’ infra and code structure in multiple diagrams.
Here are some examples below:
Adjacent to the problem of documenting architectural designs is the challenge of documenting software design (i.e., OOP and design patterns).
In the 2000s, the Unified Modeling Language (UML) was the go-to approach for software design. UML was introduced in the 1990s as a general-purpose language to visualise a software design, break down its internal components in a Class structure, and model their relationship.
However, it was built to solve an outdated problem. Its main focus was modeling class relationships in source code—which worked well for Monolith architecture and academic projects—but it relied on strict rules and notations for relationships and associations. For most engineers, it quickly became too complex to follow and use, especially in modern software design.
In software design/OOP interviews, I never expected candidates to use UML; simple boxes and arrows were good enough.
Here’s a classic example of modeling a banking system using UML. Notice the annotations and arrow types used to define specific relationships.
The C4 Model
So what is the C4 model?
It’s a set of hierarchical abstractions that describe software architecture using simple graphical notation. C4 stands for Context, Container, Component, and Code, each representing a diagram at a different level of abstraction.
The idea is simple and tooling-independent. The Context view provides a high-level overview of the system and its interactions with external systems (or internal systems we don’t have context on). The Container is a view of the software building blocks, such as applications and databases, and how they communicate. The Component view is a breakdown of containers into smaller detailed flows (e.g., CRUD components). The Code view is the implementation details, focusing on classes and code structure (similar to UML). This multi-layered view supports the needs of different stakeholders—from architects and developers to product managers and analysts—by building a clear, shared understanding of the system’s architecture.
Think of the Context as viewing a country in Google Maps: you can zoom in to explore a city within the country (Container), zoom in further to a specific area in the city (Component), and finally zoom all the way in to a specific street (Code).
This layered approach is what the C4 Model provides. No complex notations, only hierarchical diagrams with clear boundaries.
For more details, I’d recommend watching this latest talk by Simon Brown where he explains why C4 Model exists:
How to use the C4 Model
With any new approach, I’d start simple. The goal isn’t to enforce a diagramming convention on the engineering team, but rather to test and explore the intuition behind explaining an architecture using the layering approach. This could involve modeling one microservice or two services, where one depends on the other. I’d recommend trying a top-down design approach. Here’s a reference diagram as a recap.
Before starting this exercise, here are some questions I’d ask myself:
Do I understand the boundaries of each diagram (Context, Container, Component, Code)?
Am I able to identify which part belongs to which diagram?
Am I abstracting too much or over-explaining my diagrams?
Would another person understand the intention behind my diagrams?
Is it easier to read compared to our existing diagrams?
Wrap up
Software documentation is a bottleneck for many engineering teams. The goal of overcoming this bottleneck is to quickly build a mental model of a system, making it easier to introduce new ideas and fully understand how everything fits together.
Having a standard process like C4 for documenting and updating architecture improves decision-making, increases collaboration, facilitates knowledge sharing, and provides smooth onboarding. C4 is tooling-agnostic and easy to follow, making it an excellent fit for any organisation.
P.S. If you enjoyed reading this post, you might also be interested in reading this post on developer documentation.
🧊 IcePanel
If you’d like to use the C4 Model, I recommend checking out IcePanel.
IcePanel is a collaborative diagramming and modelling tool for software architecture based on the C4 model.
It’s a lightweight and powerful tool to help you visualise your architecture at different levels of abstraction with a single source of truth. Great for all audiences, from technical (engineers, architects) to non-technical (product and business people).
If you found this post valuable, share it with a friend and consider subscribing if you haven’t already.