The C4 model for visualising software architecture

Introduction

Ask somebody in the building industry to visually communicate the architecture of a building and you’ll be presented with site plans, floor plans, elevation views, cross-section views and detail drawings.
In contrast, ask a software developer to communicate the software architecture of a software system using diagrams and you’ll likely get a confused mess of boxes and lines …
inconsistent notation (colour coding, shapes, line styles, etc), ambiguous naming, unlabelled relationships, generic terminology, missing technology choices, mixed abstractions, etc.

As an industry, we do have the Unified Modeling Language (UML), ArchiMate and SysML,
but asking whether these provide an effective way to communicate software architecture is often irrelevant because many teams have already thrown them out in favour of much simpler “boxes and lines” diagrams.
Abandoning these modelling languages is one thing but, perhaps in the race for agility, many software development teams have lost the ability to communicate visually.

Maps of your code

The C4 model was created as a way to help software development teams describe and communicate software architecture, both during up-front design sessions and when retrospectively documenting an existing codebase.
It’s a way to create maps of your code, at various levels of detail, in the same way you would use something like Google Maps to zoom in and out of an area you are interested in.

Level 1: A System Context diagram provides a starting point, showing how the software system in scope fits into the world around it.

Level 2: A Container diagram zooms into the software system in scope, showing the high-level technical building blocks.

Level 3: A Component diagram zooms into an individual container, showing the components inside it.

Level 4: A code (e.g. UML class) diagram can be used to zoom into an individual component, showing how that component is implemented.

The C4 model is an “abstraction-first” approach to diagramming software architecture, based upon abstractions that reflect how
software architects and developers think about and build software. The small set of abstractions and diagram types makes the C4 model
easy to learn and use.
Please note that you don’t need to use all 4 levels of diagram; only those that add value – the System Context and Container diagrams are sufficient for many software development teams.

Different levels of zoom allow you to tell different stories to different audiences.

Hover your mouse over the diagram, find elements with a , and double-click to zoom-in.