Introduction
Diagrams are a great way to visually communicate something. However, the majority of software architecture diagrams don’t really express what they intend to, lacking description of its elements and with lots of implicit notations only understood by who drew the diagram. Also, they try to express more than one vision (high level, infrastructure, flow order, etc) in only one diagram, making it even harder for non technical people or people outside the project to understand.
In this post, I’ll present the C4 model and how it can produce software architecture diagrams that are inclusive to non-technical people, easier to understand and, consequently, better to document our software systems.
The C4 model
The C4 model is a different approach to designing software architecture diagrams. It has a concept of four main hierarchical levels of diagrams and prioritizes abstractions over notation. What this means is that common types of elements are more important than types of boxes and types of arrows with implicit meanings. Notations cause confusion and limit the people who can read the diagrams to those who know the notation or the project.
The abstractions exist to help those who draw the diagrams, in contrast to notations that need to be known by everybody who reads the diagrams. The idea is that the diagrams should be understood by themselves, without any prior knowledge of the project or the notation. It should assist the communication inside and outside the team.
It also has a clear definition of the scope of each diagram, with complementary diagrams, for example, for showing the sequence of events, or the infrastructure where the system is deployed at.
Main diagrams
The levels of diagrams work as a map, where we zoom in from country to city to see more details.
In the image below we zoom in on the system to see its containers, zoom in on a container to see its components, and zoom in on a component to see its code.
System Context
The first level diagram gives a context of how the system interacts with the users and other external systems. Details about technology should not be on this level and it should be understood by non-technical people.
Here we can see what is in the scope of our system and what is not. In addition, we see the interactions of our system with users and external systems.
Elements in this diagram:
- The system in scope;
- Users/people and their interactions with the system;
- External systems and their interactions with the system.
Containers
The containers diagram shows the containers inside the system boundary. Containers in the C4 model have no relation to docker and other container runtimes; they are just a name for a part of the system. Containers are almost always separately deployable applications that compose a system and that communicate with each other through inter-process communication or via network. Examples of containers are: single-page applications, desktop applications, APIs, databases, queues, event topics, and storage paths.
At this level, we should start describing the technology used in the containers and in the interactions. For instance, “Mobile App - [Container: Xamarin/C#]”, “Makes API calls to [JSON/HTTPs]”.
It still shows the users and external systems, but in this level, it shows the interactions with each container. In the diagram below, the user interacts with the Single-Page Application, and not with the Internet Banking System boundary.
Elements in this diagram:
- The system boundary;
- Users/people and their interactions with the containers;
- External systems and their interactions with the containers.
Components
The components diagram shows one container broken down into components and their interactions with each other and other containers or external systems. Components are important units of code; they may be interface elements in frontend apps, controllers in APIs or pages in web apps.
This level is recommended only when judged useful because the more we zoom in, the harder it is to maintain it updated.
Elements in this diagram:
- The container boundary;
- Other containers and their interactions with the components of the container in scope;
- External systems and their interactions with the components.
Code
In the code diagram, we can give details of the components with UML class diagrams or other similar diagrams.
This level is not recommended because it is very difficult to keep updated unless automatically generated from the source code. Even then, it should be used only when strictly necessary.
Elements in this diagram:
- The component boundary;
- Classes and interfaces within the component.
Supplementary diagrams
C4 has more diagrams that can be used when necessary:
System Landscape diagram
One level above the system context diagram. Useful if showing more than one system is needed.
Dynamic diagram
Similar to the UML Sequence diagram. Shows the order of the interactions between the elements.
Personally, I find the UML sequence Diagram easier to understand even for non-technical people, because they have an order from top to bottom and from left to right, so I normally use it instead of the C4 dynamic diagram.
Deployment diagram
Describes the infrastructure and how the containers of the system are deployed in it.
Here are more details about these diagrams.
Some important notes
- Diagrams should have title and their type on the header;
- Acronyms should be avoided to make the diagrams inclusive for everybody;
- Elements should have their type and the description of their responsibilities;
- Interactions between elements should have one and only one direction (no lines with zero or two directions) and be descriptive. Example: “sends emails using” instead of “uses”;
- Interactions don’t need a response line. Two lines may be used only if the interaction may start from both elements;
- The direction of the interaction doesn’t matter as long as the description matches it;
- Types of boxes and color should be complementary and not required for understanding the diagram.
Diagram review checklist
There is a checklist tool we can use to review our diagrams here.
Diagram as code
It is highly recommended to create C4 diagrams as code. It makes them easier to change and maintain updated. I’ve talked about diagrams as code in this post.