Documenting the Architecture of Your Projects With the C4 Model

One of the definitions used to approach software architecture is that it is responsible for defining the parts of a project and the technological strategy. And, like any strategy, there must be an ongoing process of review and update. That's why, here on the Zup Open Source team, we're using the C4 model.

Having a view of your project's architecture is crucial in several aspects, as it helps you answer questions such as: how can my system integrate internally or with other systems? Or, how can I guarantee security between my applications? And so on.

One of the classic architecture books, Just Enough Software Architecture: A Risk-Driven Approach, mentions that to make software successfully, you have to deal with three fronts:

1. Partition: The art of dividing the problem into small pieces to understand a whole.
2. Knowledge: The ability to explain what is behind the architecture, how it works, but mainly why it is used, and what were the necessary decisions to reach this final result.
3. Abstraction: A software architecture definition is difficult to define precisely, so using stereotypes helps understand and solve complex problems.

Another reference book in the area, called Fundamentals of Software Architecture: An Engineering Approach, states that the constant analysis of architecture is one of the requirements expected by those who work with architecture within technology.

Given the alternatives available on the market for documenting software architecture, which one might be a good choice?

What is the C4 Model?

Documenting the architecture of a project is often a painstaking process that requires time, knowledge of tools, and techniques for diagramming and documentation.

In practice, the biggest challenge within software architecture documentation is to avoid two scenarios:

1. Architectural documentation is very complex and, as a result, tends to become confused and obsolete, losing its purpose. In other words, documentation takes time and becomes unusable in a short time.
2. "Poor" documentation with little information or incorrect information that we don't spend time creating, but it is useless.

In either case, the result is that they are more of a hindrance than a help.

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

It came about to help solve the problem of documenting faulty architectures that are difficult to understand and maintain. The C4 model clarifies the documented architecture and spans several levels relevant to the various “personas” involved.

The Levels of The C4 Model

The C4 model has four types of diagrams, each of which has a different level of detail and target audience. The idea is to dig deeper into the details and information from the previous story.

A better allusion would be with Google Maps, which you can zoom in to reduce or enlarge the architectural design. If on a map, for example, we have Continent, Country, State, and City, on the C4-model we have:

• Context.
• Container.
• Component.
• Code.

Below, we will better understand each of the levels:

Level 1: Context

It's the first step in our design. The idea is to show interactions in a macro way, without much detail, focusing on communications and dependencies between systems and users composing and interacting with the software.

It is a diagram that can (and should) be consumed by all the "personas" of the project, both technical and business, and that interact directly or indirectly with the system.

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 on the architecture and technologies used.

The idea is to show how the system is (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, support professionals, etc.).

Level 3: Component

Upon reaching the third level, we take a further step in the details compared to Container, this time with the description of the parts that make up these containers. At this level, information about interactions, responsibilities, and technologies used appears in more detail than at previous levels.

A system will likely 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 maintaining it.

Level 4: Code

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

Generally speaking, this level of detail is not recommended and is an optional view. Furthermore, several tools currently generate this type of diagram automatically.

Why Do We Adopt the C4 Model for The Architecture of Our Projects?

Within Zup's Open Source team, the technology and architecture of each project are viewed strategically, as we understand that having a clear vision of what we are building - both at a technical and business level - contributes to the evolution of the product and the creation of solid roadmap.

An excellent technological product is based on solid architecture and its respective documentation. Therefore, with the C4 model, we could have this vision in an agile way and add value to the project.

Furthermore, this model allows us to share the project's architectural knowledge with the community, simplified but with purpose and value.

How We Use the C4 Model

On the team, we advocate that the architectural documentation needs to stay close to the code and is the responsibility of all team members. Like the code itself, our C4 model is inside a Git repository.

It guarantees all the benefits of versioning. By the way, we strongly believe in the doc as a code, where we also have all our documentation.

To facilitate the visualization and maintenance of the C4 model, we adopted the model of a single repository per project, available via S3 and deployed using GitHub Actions.

What Tool Do We Use?

We adopt the architectural design as code with C4-Builder. The primary point is that it has different ways to configure and export. However, among the existing settings, we chose to use it via markdown, since it is the tool that:

• We already use it for our documentation;
• Our Technical Writers team recommends;
• It is doc as a code, being in line with our purposes and guidelines;
• It has an action for GitHub Actions, a tool used in our pipeline, which facilitates the integration and use of the instrument.

How Do We Align the C4 Model With the Documentation?

Following our technical documentation pattern, our C4-model models are available online via a website referenced in a menu in the official documentation.

It is the responsibility of the Engineering team, together with the Technical Writing team, to keep the C4-model up to date with each update in which it is necessary to update the architecture documentation as well.

You can check the C4 model of each project:

• Charles CD
• Horusec
• Ritchie CLI
• Beagle

C4 Model: The Key to The Evolution of a Project

Good documentation is at the heart of any Open Source project and is generally the gateway to open source projects. With architecture, this is no exception.