It’s the little details that are vital. Little things make big things happen.
- John Wooden

The Egyptian pyramids: Seen in the big picture, they are a masterpiece of architecture; seen in detail, they are only small stones placed one on top of the other. Software is typically also composed of small units. To create a good overall picture, the small components must harmonize well with each other.

Many people in the software industry are familiar with the following situation: Ideas for a software architecture are collected, discussed, various approaches are visualized on a whiteboard or flipchart, and an architecture is agreed together. As a protocol of the meetings, the visualized architecture is photographed and saved in a wiki tool for the future.

A few weeks later, a new employee joins the project and wants to get a rough overview of what the software is about and how it is actually structured (or an employee returning after vacation 😉). This task is not easy, because sometimes labels on arrows are missing and same symbols are used for different elements of the architecture. For this reason, the employee asks the responsible software architect, who, however, does not really remember the individual details either.

Conclusion 1: The architecture diagram does not by itself provide the information needed for a basic understanding (in the best case more than just that). There is simply no general standard for modeling software architectures.

In a different situation an existing software requires a new feature, which is associated with architectural changes. Due to the non-uniform and unclear way of documentation, the concrete changes are difficult to represent. Thus, valuable time can be lost by first having to reconstruct the architecture.

Conclusion 2: Changes to the architecture are always time-consuming with such a documentation style.

A short excursion into other industries

In other industries, such as building architecture or electronics, such modeling activities are largely standardized. Standards exist for the individual circuit symbols in electrical circuits, such as IEC 60617. In addition, abstract models exist for different views of a circuit diagram, which can be viewed here. It is important to mention that these models are actually used in practice!

It would be nice if standards of this kind existed for software architectures. A few important requirements for this would be:

• Outsiders should understand the architecture as simply as possible by looking at the diagram
• Use of uniform and simple terminology and symbols
• Different views of the software so that each stakeholder has a suitable overview over the software

The last point can be compared to a map that you zoom into (see figure 2). This allows to map different levels of detail of the architecture. This is required for different stakeholders of the software.

For example, a software developer needs a much deeper insight into the architecture than a colleague from sales.

But UML is a standard, isn’t it?

Absolutely correct. UML (Unified Modeling Language) is a standardized modeling language whose goal is to specify, design and document software systems. UML is known to many people and some of them in the software industry have already had to deal with it. Various diagrams can be mapped with UML. Here is a small and incomplete list (taken from here)

• Behavioral diagrams:
  • Activity diagram
  • Use Case diagram
  • Sequence diagram
  • State machine diagram
  • …
• Structural diagrams:
  • Class diagram
  • Object diagram
  • Deployment diagram

A good survey of the different types of UML diagrams can be found here.

UML is very interesting and some diagrams are wonderful for modeling ideas graphically! Small class diagrams representing a design pattern is a good use case for a UML diagram, because classes, interfaces, inheritances, data and behavior can be easily represented in UML.

However, to visualize the whole application architecture with UML, different diagrams would have to be drawn and brought together. This costs time and can be very confusing under certain circumstances with large architectures. In addition, the diagrams may cause confusion for people without a technical background, as they are not familiar with the notation. We can and should use UML, but for the situations it should be used for: to describe design patterns and small parts of an application in detail.

But how can we then describe software architectures?

The solution: The C4 model

In 2006, Simon Brown developed a simple and comparatively easy way to describe software architectures. In principle, this works analogously as shown in figure 2 with the map. There are four different “zoom levels” of the architecture (this also explains the name 😉):

1. System Context
2. Container
3. Components
4. Code

Before looking at the individual levels in a little more detail, it is important to agree on a common abstraction. This is also used again afterwards in the charts. The following list provides a brief overview:

• Person: A human or group of humans interacting with a system.
• Software System: A software system is the highest level of abstraction and describes something that provides value to its users (both human and technical). The software being modeled and other systems on which the software system depends are included.
• Container: Not Docker! In the C4 model, this means individual applications or data stores. Typically, they are individually deployable/executable units. (Examples: a Spring Boot application, a PostgreSQL database, …).
• Component: Just like container, this term can have many meanings. In the C4 context, a component is a grouping of related functionalities behind a defined interface. Unlike containers, components cannot be executed individually. Example: A REST controller from Spring Boot is a component.

Deeper explanations and explanations can be read on the official site.

It is important to mention that the C4 model merely describes how an architecture should be described in an understandable way. The model does not describe a process or a notation. However, there is an official proposal for the notation, which is used in the following subchapters.

The following subchapters provide a brief insight into the different abstraction levels, which can be read in more detail here. This is accompanied by an example from the official site, in which an online banking system is modeled graphically.

Level 1: System Context

This diagram shows the overview of a software system with all interactions. Not only user interactions are meant, but also external software systems. The target audience of the diagram is not only the developer of the software, but also outsiders.

Figure 3 shows an example of a System Context diagram. In the center you can see the software system, which is describes. Around the outside the people and external software systems involved are shown and how the components relate to each other.

Level 2: Container

At this level, a view is taken into the system which is described in this example. The individual elements of the system are described at a high level with containers. If relevant, external persons and systems can also be mapped.

Figure 4 shows a container diagram. Each container is an autonomously executable unit. Rough technological decisions can be documented at this level.

Level 3: Component

The penultimate level considers the individual containers from the second level separately and divides them into components. This view is comparable to a package diagram from UML. The banking example can be viewed here.

Level 4: Code

The last level considers the components defined from level 3 individually. Usually class diagrams or Entity-Relationship-Diagrams are located at this level. Often this level is considered optional, since such a deep level is not necessary for a rough understanding of an architecture.

C4-Model vs. UML

In our view, the C4 model and UML must not be contrasted; both pursue different goals and have their reason for existence. While the C4 model describes how a concrete system architecture can be documented in a way that is easy to understand, UML focuses on a uniform notation and a wide range of diagrams. In fact, we find that the diagrams resulting from the C4 model should be supplemented with UML diagrams if necessary, because the four diagrams do not represent a complete architecture documentation under any circumstances! If you are a fan of UML, the C4 diagrams can be mapped with modified UML notation.

Closing words

The C4 model has definitely convinced us and we will use it again — if it fits. In one of our projects, a colleague was able to familiarize himself with the architecture we had changed without much effort after taking parental leave.
We like using the standardized and lightweight model to design architectures efficiently and to document them in a way that is understandable for all target groups. A big advantage is the integration of the C4 model with arc42, ArchiMate and other tools. We have used draw.io with an extension so far and have been satisfied with it.

Related articles/videos

• Official C4 Model Website
• 

  Modeling Software Architecture With C4 | by Jakub Kapuscik | Better Programming

  Jakub Kapuscik ・ Jan 31, 2020 ・

  Medium

Michael Weidmann is writing for the devlix Blog at https://www.devlix.de/blog
This article was published first here (german): https://www.devlix.de/die-vier-cs-der-softwarearchitektur/