We had the opportunity to talk with Kamil about a very interesting topic — system architecture documentation. How do you create documentation that includes all the necessary information without overwhelming it with details? Kamil introduced the approach called “C4.” The name comes from the fact that it works on 4 levels: Context, Containers, Components, and Classes.
The “C4” approach was also presented at one of the early CSD+ meetings when we were looking for easier ways to represent system architecture. The need for a new solution arose from experiences during conceptual meetings with clients. Unfortunately, not everyone understands UML notation, which caused problems in agreeing on key information.
C4 is a simplified way to show architecture by dividing it into 4 diagrams:
- Context – the general context in which the system will operate: main actors/roles, other systems, main processes
- Containers – high-level decisions, the “containers” for components, high-level communication, information for developers on where work should be done
- Components – logically cohesive parts of functionality (e.g., services), the system operation on the level of flow between components
- Classes – class structures, application architecture (organizing source code)
It’s also important that for each C4 level, we approach the following aspects differently:
- Purpose – why this diagram is created and what it should show
- Structure – what blocks make up the diagram
- Motivation – what we want to communicate to the document’s audience and what insights can be discovered while creating it
- Audience – who the audience is and what they might need at this level of detail
In C4, we use simple, often self-explanatory diagrams and a single, well-defined notation. When implementing the C4 methodology, we use the same set of abstractions and notation at every level of detail, communicating effectively with all potential audiences. The C4 approach ensures consistent “scaling of information” without semantic gaps. This allows us to verify the architecture — in terms of its current alignment with requirements and context. Verification is facilitated by the smooth scaling of focus from the general overview to detailed specifics, enabling gradual familiarization with the context.
An example of C4 usage can be found in our GitLab Wiki at:
https://git.inf.nekken.loc/nekken-public/c4-demo