How to zoom in and out of your software architecture using the C4 model
Discover the C4 model and learn how it can be used to represent your architecture at varying levels of detail
Documentation is an essential part of Software Engineering.
There are different kinds of documentation; I will propose a technique to produce adequate architecture documentation in this post. The method I will expose is called the C4 Model. Simon Brown invented it, and it consists of showing your system architecture in four levels.
With the C4 Model, you should be able to zoom in and out depending on the audience and the level of detail you want to use to analyze your system.
The C4 Model
C4 stands for Context, Container, Component, and Code.
Each one is a diagram representing different aspects of the system. From the Context, the highest level, to the Code, the lowest. The four levels have different purposes and can be understood by different audiences.
Let’s start with the first one.
Level 1: Context
In the above example, the Online Store represents our system. A user interacts with it to buy products. The Online Store uses a Payment System to process payments and store credit card data and an Email System to send emails.
The Context diagram needs to clarify the following points:
Who uses the system
What are other systems it interacts with
What is the purpose of the interactions with the other systems
Technology specifications and interaction protocols are not relevant in the Context diagram.
The Context diagram focuses on the interaction between the system user (a human or another system), the interaction with other systems, and the purpose of those interactions. The arrows in the diagram should express the interaction among the systems.
The audience for this diagram is technical and non-technical people.
Level 2: Container
The above diagram shows the Container diagram of the Online Store system. As you can see, there is a stroked rectangle representing the boundaries of the Online Store itself. Inside it, three containers are the parts composing it: a web app, an API, and a database.
The Container diagram focuses on:
High-level technology choices
Communication protocols
Responsibilities across the system
As a developer looking at this diagram, you should understand where the code for a new feature should be implemented. If you look at the diagram, you can see the technologies chosen for each Container (Vuejs, Node, and MySQL). A developer looking at this diagram needs to understand the technologies used.
The audience for this diagram is technical people from both the engineering team and outside of it.
Level 3: Component
The above diagram shows the component diagram of the API Container for the Online Store. Inside it, you can see three modules composing it: an Orders module, a Products module, and a Notification module.
This diagram should show only the components you need for your specific purpose. If your API includes a logging module, you should show it in the diagram only if it is relevant. For example, if you need to make a presentation for a new feature, if the logging module is irrelevant, don’t show it.
The Component diagram focuses on:
Frameworks and high-level libraries used
Understand the structure of the codebase
Level 4: Code
Don’t do it.
This might seem a bold take, but it is my advice. I believe representing the code in a diagram only applies to specific scenarios. Most of the time, having the first two diagrams and using the Component diagram as needed is more than enough. Also, this level of documentation changes frequently, as does the code.
If you need to do it, don’t fall into the trap of starting from this level.
I experienced the style of starting from the code and “generating” the architecture from it. It doesn’t work if you don’t have a big picture in mind of your system; your code won’t give it to you. Always use a top-down approach.