How to define the architecture of your system with C4 Model?

Although in this Agile world the importance of the software architecture of a system is sometimes underestimated, we could say that in this world of microservices, containers, Kubernetes, Cloud and services it is crucial to answer questions about the security of my system, the integration with other systems, etc.

On the other hand, documenting the architecture of a project is a complex and meticulous process that requires time, knowledge of diagramming and documentation tools and techniques.

There are several models to define the architecture; some true classics like the 4+1 model (one of our favorites along with the SunTone AM). In this article we are going to talk about the C4 Model to define the architecture of a system.

That said, the goal of the C4 Model is to avoid 2 things:

  • That the documentation of the architecture is complex, confusing and that in the end it ends up obsolete, thus losing its main purpose.
  • That the documentation is poor, with little information or with incorrect information, which does not take us time to create, but which is useless.

What is C4 Model

The C4 Model is a documentation format created by the engineer Simon Brown between 2006 and 2011, and based on the 4+1 models and the UML.

This model emerged to help solve the problem of faulty documentation of architectures that are difficult to understand and maintain. The C4 model clarifies the documented architecture and covers various levels relevant to the different «people» involved.

C4 Model levels

The C4 model has four types of diagrams, each of which has a different level of detail and target audience. The idea is to delve into the details and information of the previous story (like zooming in)

In the C4 model we find the following levels:

  • Context
  • Container
  • Component
  • Code

Next, we are going to see each of the levels on an example documented with the C4 Model, the «Horusec C4Model», where Horusec is an open source tool that performs a static analysis of the code to identify security flaws during the development process.

Level 1: Context

It is the first step of our design. The idea is to show the interactions in a macro way, without much detail, focusing on the communications and dependencies between the systems and the users that make up and interact with the software.

It is a diagram that can (and should) be consumed by all the “people” in the project, both technical and business, and who interact directly or indirectly with the system.

Let’s look at the diagram for the example:

C1-Context (

Level 2: Container

The second level shows the system in more detail, describing its containers (not to be confused with Docker) and how they communicate/interact. At this level, emphasis is placed on the architecture and technologies used.

The idea is to show how the system is built (or will be built) in a macro way. A container can be a web application, a database, a file system, among others. It is a diagram to be consumed by the technical team, which interacts directly or indirectly with the system (development professionals, support professionals, etc.).

In the example we have:

Vista previa de imagen
C2-Container (

Level 3: Component

Upon reaching the third level, a further step is taken in the details regarding the container, this time with the description of the parts that compose it. At this level, information about interactions, responsibilities, and technologies used appears in more detail than in previous levels.

A system is likely to have more than one component diagram. It is a diagram to be consumed by the technical development team, which is recommended only in cases that have generated value. There is a commitment to keep it.

In our example we have 4 diagrams:

We can find all the information from: C3-Component (

Nivel 4: Código

At the last level, the C4 model shows -at the code level- how each component is implemented and for this it uses the UML class diagram.

In general, this level of detail is not recommended and is an optional view. In addition, several tools currently generate this type of diagram automatically.

Herramientas para C4 Model

A very powerful tool is C4Builder, which allows you to define the architecture in different formats (such as plantuml or md) and export the architecture documents.

C4Builder is based on these tools:

  • PlantUml creates diagrams from plain text.
  • Markdown creates rich text documents from plant text.
  • C4Model the idea behind the code maps.
  • C4-PlantUML C4 syntax support for generating plantuml diagrams.
  • Docsify create a single page site based on markdown files.
  • vscode-plantuml plugin for Visual Studio Code to view diagrams at design time.

Examples C4 Model

These examples can give you an idea of ​​how an architecture is defined with a C4 Model:

✍🏻 Author(s)

Leave a Reply

Your email address will not be published. Required fields are marked *