C4 Model

2 minute read #software architecture

“Boxes and lines” type of diagrams can be a quick way to help communicate your ideas during a software architecture discussion. But it usually lacks context and details.

This is where the C4 Model helps.

C4 Model is a set of guidelines for clearly visualizing software architecture. It provides context, while remaining concise.

It’s a methodical way to improve on the “boxes and lines” method we tend to use.

The C4 stands for the 4 levels of system diagrams. We go from top to bottom in the system hierarchy. Think of it like we’re zooming in on a map.

Context #

We start with the big picture. This shows the system, its dependencies, and the users from a bird’s eye view.

Container #

Container: A term to describe service and app level components.

Still in big picture mode, but going a bit into detail here. This will show the containers and their relationships.

For example, you will see database, web app, mobile app, etc. here.

Component #

This is where the logical components of a container, and their interactions are described.

Code #

This is for visualizing the actual code composition. You can automate this step by generating class diagrams from code. Do not spend any time on this level.

Guidelines #

What I like about the C4 Model is that it gives you a structure with the 4 levels, and a checklist you can go through to make sure you are not omitting anything.

Provide context. This is achieved by the multiple levels of visuals, as well as concise description of each component you are drawing.

Provide legends. When using shapes and colors, be sure to use proper annotations to explicitly show the different kinds of figures.

Don’t forget to label the relationship lines.

Use non-ambigious descriptions for relationships.

Use colors, shapes, and size to complement a diagram. These visual improvements should only be there to complement the base diagram. If you take away these, the diagram should still be useful.

Tell a story. The diagrams are there to help you communicate your ideas with people. Use it to tell a coherent story.