Software architecture documentation using the C4 Model

Understanding the C4 model

With the C4 model you document your software in different layers that can help you visualize the design and structure of your software. In this blog post, we’ll explore the principles of C4 documentation and how it can help you document your software projects. And remember, one of the most important things with documentation is that it needs to be reflecting the truth. This implies that maintaining documentation is very important. You better have no documentation than disinformation. Always keep this in mind when deciding the level of detail you are going to document. The C4 model can help you with this.

The C4 model is a framework for visualizing software architecture in 4 separate layers. It is developed by Simon Brown (https://simonbrown.je/). It consists of four levels of abstraction, each offering a different perspective on your software system:

• C1 – Context diagram
  This provides the highest-level view of the system and shows how it interacts with external dependencies and how other dependencies interact with the system. It’s often represented as a simple diagram with your system in the center and external actors surrounding it. As the name says it gives a view on the context where the system is being used.
• C2 – Container Diagram
  At this level, you zoom into the system and identify high-level containers or components within it. This can for example be (micro)services, databases, etc. that are part of your application.
• C3 – Component Diagram
  Within each container, you can dive deeper into the components or classes that make up that container. This can for example be class diagrams or sequence diagrams. Component diagrams help you understand the internal structure (class diagrams) of containers and how they interact with one another (sequence diagrams).
• C4 – Code Diagram
  The lowest level is the code diagram, where you can document specific implementation details, such as classes, interfaces, and their relationships. While it’s not always necessary to include code-level diagrams, they can be useful for complex components. But remember that documentation should reflect the truth so maintaining diagrams on this level can be time consuming.

Goals of C4 documentation

Clarity

The primary goal of C4 documentation is to provide clarity. Use simple and clear notations in your diagrams. Avoid overwhelming your audience with unnecessary details. Remember, a good diagram should be easily understood at a glance. That is one of the main reasons why the 4 different layers are used. When someone is new to the system he or she can start with the context diagram and dive deeper into the system step by step. In this way it is easier to start understanding the system.

Relevance

Include only the information that’s relevant to the specific level of abstraction. Context diagrams should provide a high-level overview, while code diagrams should focus on implementation details. Depending on the audience you can use the diagram that is most useful.

Keep It Up to Date

Software systems change over time and as I mentioned earlier it is very important that documentation reflects the truth. So it’s essential to keep your C4 diagrams up to date, reflecting the current state of your architecture. Incorrect or outdated documentation can be more harmful than having none at all because it gives your audience a wrong view of the current situation.

Consistency

C4 does not dictate a specific notation (e.g. UML) so that is up to the team to decide. Most important is to maintain a consistent visual style and notation across all your C4 diagrams. This makes it easier for anyone reviewing the documentation to understand and follow the architecture.

Annotations

Use annotations and descriptions to add context and additional information to your diagrams. Explain the purpose of each container, component, or class and any specific interactions or dependencies.

Collaboration

Involve the whole team in creating and reviewing C4 diagrams. Architecture is a something the whole team is part of. Each member may have unique insights and perspectives.

A practical example

To bring C4 more to life a made up a fictive case about a software system. Imagine you have a software system that generates reports about companies in the Netherlands. Let’s call the system “CompanyManager”. To give you some context here are some highlights about the situation. The system:

• has a customer portal where customers can download reports
• has an API that customers can use to get reports
• generates reports but to do this the system is dependent on an external system from the KVK (Kamer van Koophandel) to get data about companies
• has a management portal for employees where they can manage users that have access to the system
• uses DigId to authenticate customers to the customer portal
• uses AzureAD to authenticate employees to the management portal

Given the requirements above the C4 documentation could look like the following diagrams.

C1 – Context

What you see in the diagram below is in essence the system with its borders. It shows what external systems the system is dependent on and what actors use the system. How the system works internally is described in a very abstract way. More detail about how the system works internally will be designed in the other diagrams.

C2 – Container

In the C2 diagram below we see more detail about which portals we have and what services are available. Next to that we see how the services communicate with each other. Of course this is just a small example and I have added some details but it is up to the team to decide what details you want to provide. It always depends on the audience the design is targeting. The most important rule here is to just add details that are relevant for the target audience. When you notice the design is getting to complex consider removing details and add them on different diagrams in the C3 layer.

C3 – Component

Each level in the C4 model can consist of multiple diagrams. On the lower levels this is more often the case than on the higher levels. The sequence diagram below could be one of the diagrams to describe the components in the system and how they interact with each other in certain processes. Next to sequence diagrams other diagrams could be added as well (e.g. flow charts of certain processes).

C4 – Code

Code diagrams are the lowest level according to the C4 model specification. It is a level that is not used that often because it contains very low level details about the internal working of components. This can be relevant to technical people working on those components but often the diagrams can also be generated from IDE’s. So my advice would be to do this only if it is really relevant or make a more generic diagram like the one below. This example just shows how the internal structure of the different types of components should be. The specific implementation of each component is not designed but can be found in code or generated from that code.

Conclusion

The C4 model offers a structured and effective way to document your software architecture. It focuses on relevance, clarity and consistency. This is done by using the 4 abstraction layers. Each abstraction is useful for a different audience. By using the C4 principles, you can create architectural documentation that not only supports your development process but also enhances collaboration (inside and outside your team) and onboarding.

On the website https://c4model.com/ you can find more information and examples on how to use the concept of C4 models. It is a relatively simple model that you can introduce to your team and start using right away.

Sources:

• https://c4model.com/
• https://www.youtube.com/watch?v=x2-rSnhpw0g