Introduction

Software diagrams visualize the intents and relationships of complex systems; that’s the idea, anyway. In reality, software professionals and their clients often fruitlessly engage in this dance of breaking down requirements and design through diagrams that often make sense at the time the diagram is done. And, when someone else comes to try to read or use this artifact, it’s nearly useless as all context and meaning is missing. Despite this, the desire to make more and more diagrams remains. Software diagrams share a very similar relationship to another medium of visual representation–a map.

Maps have been used by humans for centuries, tracing back as early as the civilizations of Babylonia, ancient Greece, and ancient Rome. They endured as a useful tool because of what humans could do with them. Humans created maps as a way to record what they observed; as they travelled, they would note down landmarks such as sources of water, food, or other people. They used maps to share this knowledge among others who might not have observed what was recorded. Maps were also used as a means to abstract critical information about the terrain. This information proved to be very valuable.

The value of a map lies in how it highlights specific elements (landmarks) and the relationships between those elements (rivers, roads). For example, a good map could be given to someone and could be used to find a source of water, hunting grounds, or a trading post. The value was that the map was nearly self-explaining; it didn’t require the original authors of the map to explain it. A key element of that attribute is–a key or legend. Coupled with descriptions of the meaning of the symbols on the map as well as some annotations, maps have endured as a useful artifact for transmitting knowledge about a terrain. In a similar vein, the hope for software diagrams was to distill knowledge in a shareable format about an abstract terrain of code, modules, and containers fitting into large, complex software systems.

C4 Model

The C4 Model captures the critical aspects to visualizing software systems. It also takes inspiration from the essential components of maps and translates how those can be used in visualizing software.

Alternatives to C4

“Just use UML”

UML often comes up when discussing options for diagramming. It unfortunately falls into the trap of being useless. It shares a similar fate as object-oriented programming; used by academics who don’t have experience in shipping software on time.

“Just use a whiteboard”

A second alternative suggested is to use a whiteboard. However, this suggestion doesn’t actually help in diagramming software; all it’s saying is to put it on whiteboard without regard for how to represent the ideas. This approach falls into the trap of individuals with terrible penmanship and no experience diagramming creating boxes on a board that are only useful for an hour before being irrelevant.

The reason diagramming software challenges software professionals is that it often has different audiences with different interests, i.e. users, product managers, technical leads, developers all have a different interest and technical understanding looking at software diagrams.

What is needed instead is a way to create understandable abstractions, that allow consistent communication of ideas and relationships despite the demands for different audiences, interests, and contexts. In particular, maps accomplish this through the use of a key or legend.

C4 Abstractions

A Software System

• each system has 1+ containers (containers run code or store data)
• each container has 1+ components
• each component has 1+ code elements

The 4 levels of C4 are:

1. Context
2. Containers
3. Components
4. Code

In C4, Diagrams Should …

Have A Title

• describe the diagram type
• describe the scope

Be Consistent

• consistent notation
• consistent symbols

Not Use Acronyms

• see Musk’s email at Tesla

Have a Key/Legend

• explain ALL notation
• use icons to supplement text, not replace it
• use shapes, colors, lines only if the diagram ALREADY makes sense

Stand Alone

• it should be readable enough to stand alone
• any narrative should COMPLEMENT the diagram, rather than explain it

C4 Box Anatomy

Title/Name
[type]

Short Description

C4 Line Anatomy

• favors 1-direction lines showing the most important dependency or data flow
• uses annotation to be explicit about the purpose of the line and direction
• specifically summarizes the intent of the relationship
• adds text to make the intent specific
• only shows 2 directions when the INTENTS are different

examples

1. Thing A -> Tepends on -> Thing B
2. Thing A -> Talls -> Thing B
3. Thing A -> Makes API calls using -> Thing B

Software Tools

• Do not use general purpose drawing software (vizio, drawio, lucid chart); it’s not good for software
• Use Graphviz
• Use C4-PlantUML
• Use Structurizr (made by Simon Brown)

Software Diagram Review Checklist

The C4 Model also provides a checklist (yes or no questions) to verify if your visualization contains the essential components.

General

1. Does the diagram have a title?
2. Do you understand what the diagram type is?
3. Do you understand what the diagram scope is?
4. Does the diagram have a key/legend?

Elements

5. Does every element have a name?
6. Do you understand the type of every element? (i.e. the level of abstraction; e.g. software system, container, etc)
7. Do you understand what every element does?
8. Where applicable, do you understand the technology choices associated with every element?
9. Do you understand the meaning of all acronyms and abbreviations used?
10. Do you understand the meaning of all colours used?
11. Do you understand the meaning of all shapes used?
12. Do you understand the meaning of all icons used?
13. Do you understand the meaning of all border styles used? (e.g. solid, dashed, etc)
14. Do you understand the meaning of all element sizes used? (e.g. small vs large boxes)

Relationships

15. Does every line have a label describing the intent of that relationship?
16. applicable, do you understand the technology choices associated with every relationship? (e.g. protocols for inter-process communication)
17. Do you understand the meaning of all acronyms and abbreviations used?
18. Do you understand the meaning of all colours used?
19. Do you understand the meaning of all arrow heads used?
20. Do you understand the meaning of all line styles used? (e.g. solid, dashed, etc)

Takeaway: Focus on abstractions first, notation second

Demo

Let’s put the C4 model into action. For our tool, we will be using Graphviz. Graphviz is a graph visualization software that represents structural information as diagrams. Networking, software engineering, database, web design, machine learning, and visual interfaces for other technical domains rely on graphviz for visualizations.

The Graphviz layout program takes as input a graph represented in a text language. It then makes diagrams in useful formats, such as images (png, jpg) and vector graphics for web pages (svg), and pdf and postscript for inclusion in other documents.

After creating the textual representation of this diagram, Graphviz renders it to our desired format. For this example, a traditional web architecture was diagrammed.

Expand+