Introduction to C4 Diagrams: History and the Four Levels

Every architect has seen the diagram nobody can read: dozens of boxes, arrows in five colours, and no legend. The C4 model is a lightweight way to avoid that. It gives you a small set of consistent views of a system, each aimed at a different audience, so a diagram can be understood without its author standing next to it.

What is the C4 model?

C4 is an approach to describing software architecture as a series of “maps” at different zoom levels, much like zooming into a map from country to city to street. The name comes from the four levels it uses: Context, Containers, Components and Code. Each level zooms in one step on the one before it.

A short history

The C4 model was created by Simon Brown, a software architect who spent years teaching architecture to development teams. Its roots go back to roughly 2006–2009, when he developed a way of sketching systems for his training courses and found that teams struggled to explain their own designs. UML was the standard answer at the time, but in practice many teams found it too heavy or simply did not use it. Brown drew on UML and on Philippe Kruchten’s “4+1” view model, and simplified them into something developers would actually use.

  • Early 2010: the diagram types were named: context, containers, components and classes.
  • Early 2011: the “C4” name was first used.
  • 2015–2016: the fourth level was renamed from “classes” to “code”, making clear that it is not tied to object-oriented languages.
  • 2018: an official website, published under a Creative Commons licence, and an article helped the approach spread widely.

Since then, C4 has become a common vocabulary in architecture discussions, supported by tools such as Structurizr (diagrams generated from a single model, or “diagrams as code”), IcePanel and C4-PlantUML.

The four levels

  • Level 1 – System Context. The big picture: your system as a single box, the people who use it, and the other systems it talks to. Anyone, technical or not, should be able to read it.
  • Level 2 – Containers. Zoom into the system to see the separately runnable or deployable pieces: web applications, APIs, databases, queues, serverless functions. “Container” here means an independently running unit, not necessarily a Docker container.
  • Level 3 – Components. Zoom into one container to see its major building blocks and how they interact: services, controllers, modules.
  • Level 4 – Code. Zoom into a component to show how it is implemented, for example with a class diagram or entity-relationship diagram. This level is optional and is often generated from the code rather than drawn by hand.

In practice, most teams get the most value from levels 1 and 2. Level 3 is worth drawing for the parts of a system that are complex or change often, and level 4 is rarely maintained by hand.

Why it works for cloud architecture

C4 describes the structure of a system and says nothing about which technology you build it on. A context diagram looks the same whether your containers are virtual machines, managed services or serverless functions, and the same four levels apply to any cloud platform or hybrid environment. That platform independence is what makes it useful as a shared language across teams that use different stacks.

Tips for good C4 diagrams

  • Give every element a name, a type and a short description. “Orders API – REST service that validates and stores customer orders” beats a bare box labelled “API”.
  • Label every relationship with what flows and how, for example “Submits orders using HTTPS/JSON”.
  • Always include a title and a legend, even for simple diagrams.
  • Keep one level of abstraction per diagram. Do not mix users, containers and classes on the same canvas.
  • Be consistent, not clever. C4 does not prescribe a notation, so pick your shapes and colours once and reuse them.
  • Add other views when needed. C4 focuses on static structure; for behaviour, deployment or data, supplement it with sequence, deployment or entity-relationship diagrams.

Getting started

Start with a single context diagram of a system you know well and show it to someone outside your team. If they can tell what the system does and who it connects to, you are on track; then add the container level. Over the coming weeks we will publish practical guides and templates for each level here on Architect To Go.

To read more, the official C4 model site at c4model.com is the best starting point.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top