Recently, I joined a new project with a lot of legacy (not old, but legacy) code. The project kicked off only 6 months ago, but the chosen architecture was at least unusual. "Yay, something new" I said to myself and started digging through the code and architecture.

Quickly, I realized that it is really hard to keep everything in mind. In fact, humans can keep only 7(+-2) things in short-term memory. I had some experience with visualization tools like diagrams.net (formerly draw.io) or Excalidraw, but the problem is that I was jumping between different levels of detailing and it was drawing me off.

C4

Surfing the web around, I bumped into a C4 model and this video on YouTube (highly recommended). C4 is a framework that allows abstract modelling and diagraming to a certain level of details. Would you care about a specific controller when you model complex user journeys with multiple systems involved? Probably not. C4 provides a very simple (but powerful) way to be at just the right level of abstraction.

(Illustrations are from the C4 Model website)

The framework provides the following abstractions at its core:

• Person - any user of your system. For example, actors, roles, personas etc.
• Software System is the system the person interacts with. In many cases, the software system is owned by a single software development team. For example, a digital bank, an internet shop or a video-streaming service.
• Container (not a Docker!) represents an application or a data store. The main thing about containers in the C4 model is that they are separately deployable/runnable at runtime. For example, server-side applications, client-side applications, mobile apps, microservices, databases etc.
• Component is a grouping of related functionality encapsulated behind an interface. Typically, components are running in the same process space of the container. The main difference between component and container is that components are not separately deployable units.
• Code is actually a class diagram of the application.

Using abstractions it is possible to build different views on a software system on different levels.

C4 provides 4 levels of the software system. Let’s have a quick look at them.

Level 1: System Context diagram

In the system context diagram the focus is on a software system as a whole. Any people using the system would also be a good fit for this diagram. It gives a good perspective on a big picture of the software that is being built.

The System Context diagram could be helpful to present to very broad and generic audiences.

Level 2: Container diagram

Once it is clear how the software system fits into the whole environment, a useful step is to zoom in a little bit. This is where you can see databases, microservices, modules and how they communicate with each other. Container diagrams reflect high-level architecture of the software system.

The Container diagram would be helpful for discussions with architects, product owners and business analysts.

Level 3: Component diagram

After laying down high-level architecture, it is possible to zoom in even further and look at actual components of the container. Here we have major structural blocks like interfaces, endpoints, business logic components etc. This type of diagram is very helpful when the architecture is explained to software developers.

Level 4: Code diagram

Finally, if we zoom in even more, we’ll see actual classes, controllers, repositories etc. This level is not recommended for most teams since the level of details is too high. It might be useful though in some specific cases when the code-lever architecture is very complex.

Even though C4 highlights only 4 levels, it might not be true for every project. You might end up with 5, 6 or even 7 layers in your project. Just make sure you choose the right zoom depending on the audience.

Summary

In the modern software development world, where systems become more complex and complex, engineers need something to structurise the work. C4 provides a simple, but powerful framework that is easily understandable.

If you are interested in automating the C4 Component Level, you can look at Viezly. We automatically generate a diagram of the changes and provide an advanced tooling for a code review.

In the next article, I am going to provide a practical example of how to use the C4 model and what tools are available. Stay tuned.