From Good to Great: Small Details That Improve Your C4 Model Diagrams

23 Jul 2024

Visual diagrams have always been the answer for communicating complex relationships like architectures. However, creating diagrams that are consistent in appearance, easy to create, and understandable for everyone has been a challenge.

If you're unfamiliar with the C4 model, it offers a straightforward and user-friendly approach to describing system architectures through visual diagrams.

Unlike more complex models like UML, the C4 model prioritizes simplicity and efficiency, allowing readers to quickly grasp the diagrams without the need for extensive notation knowledge.

The popularity and benefits of the C4 model

The C4 model has gained significant popularity and has been widely adopted by many respected companies in the industry. Its simplicity and effectiveness have made it a go-to choice for visualizing system architectures.

By learning and applying the C4 model, you can unlock numerous benefits. It allows you to communicate complex system designs in a clear and concise manner, making it easier for stakeholders to understand and provide valuable feedback. Additionally, the hierarchical abstractions and minimal notation of the C4 model enable you to focus on the most important aspects of your architecture, improving the overall quality of your diagrams.

Whether you are a software architect, developer, or project manager, investing time in learning the C4 model can greatly enhance your ability to design, communicate, and maintain scalable and maintainable systems.

The two major concepts of the C4 model

The C4-model revolves around two key concepts.

Hierarchical abstractions

The main idea behind the C4 model is to avoid overcrowding diagrams with excessive details. Instead, diagrams are split into multiple levels of abstractions, similar to how Google Maps provides an overview image and allows users to zoom in for more specific details.

The C4 model defines four levels of abstractions, each with its own scope and intended audience.

C4 model
The four hierarchical abstractions of the C4 model.

At first glance, this may seem like a simple concept. However, by clearly defining the abstractions in the model, it enables stakeholders who previously struggled to understand system architectures to find the right level of detail. They can now grasp the overall picture or focus on specific sections of the architecture.

Notation (or lack of it)

As mentioned, the C4 model aims to create diagrams that can be easily understood without the need to learn a specific notation. In a C4 diagram, only simple boxes and arrows are used, without any complex shapes or multiple types of arrows for different connections.

If further explanation is needed for a box or arrow, the model recommends using additional text.

This approach differs from UML, where specific arrowheads or colors have specific meanings. The C4 model creates diagrams that can be understood by anyone, even without prior knowledge.

Example from Revision
An example of the C4 notation from Revision where a type and an icon have been added in addition to text to create better context.

The small but important details the C4 model

When presenting the C4 model, the above ideas usually strike a chord and excite people. However, when they start working with it, a few details often get misunderstood.

Two-way arrows

An architecture often involves data flowing in request-response patterns, where one component makes a call and receives a response. This can occur in synchronous or asynchronous patterns. When visualizing this, many people instinctively look for a two-way arrow.

However, the problem with a two-way arrow is that it doesn't clearly indicate which component initiated the call. In UML, this is often addressed using different arrowheads or dotted returning lines.

In the C4 model, there is no two-way arrow. Instead, it recommends using additional text on the arrow to convey the direction of data flow. This text should start with a verb, such as "Reads" or "Writes". By using verbs, it becomes clear that data is returned, and there is no confusion about which component initiated the call. This approach eliminates the need to understand different types of arrows or arrowheads.

Example from Revision

Colors for differencing between types

A box in a diagram can represent various elements such as a database, a user, or an entire system. When trying to differentiate one component from another, colors are often used. However, using colors can create confusion, especially when multiple diagrams use the same color to represent different things.

The C4 model advises against using colors. Instead, it recommends using additional text to explain the meaning of a box or arrow. This approach allows everyone to understand the visualization without the need to refer to a legend.

Colors for technology choices and other additional information

Another common use of colors is to indicate that one box, for example, is implemented using a specific technology or other contextual information.

In the C4 model, this is also addressed by adding more text within the box.

Colors for showing where deployed

Finally another common scenario for using colors in a diagram is to indicate where something is deployed. A box can represent a component deployed in on-premise datacenter while another color indicates it being deployed at a cloud vendor.

Instead of using colors the C4-model here recommends using a dotted box that surrounds the box to indicate an area where the box is deployed.

Example from Revision

Select a tool that leads you to success

As mentioned, the C4 model is tooling-agnostic. However, leveraging specialized diagramming tools can greatly enhance your diagram creation process, allowing you to create high-quality diagrams efficiently and maintain consistency. These tools provide helpful features and support to ensure that you and your teams can maximize the benefits of using C4 diagrams.

Revision is a powerful tool that offers built-in features to streamline your diagram creation process and enhance collaboration.

Here's why you should consider using Revision.

Efficient diagram creation

With Revision, you can create C4 diagrams efficiently. The tool offers a user-friendly interface and pre-built shapes and symbols specific to the C4 model. This allows you to quickly drag and drop elements onto your canvas, saving you time on manual formatting.

Seamless sharing and collaboration

Revision simplifies sharing and collaboration of C4 diagrams. Invite team members, stakeholders, and clients to view and edit diagrams in real-time. Benefit from version control, history tracking, commenting, and annotation features.

Integration with other tools

Revision integrates with popular project management and documentation tools like Jira and Confluence. This allows you to embed C4 diagrams directly into your project documentation for easy access and reference.