⚡ TL;DR
- Simon Brown created the C4 model as a simpler method of documenting software architecture than heavier methods like UML.
- The strength of the C4 model comes from its simplicity and flexibility, which allow it to document a variety of architectures for different audiences, from technical to non-technical.
- It consists of a limited set of abstractions arranged in 4 diagram levels — Context, container, component, and code.
📖 A bit of history
The C4 model was created by Simon Brown between 2006 and 2011. Simon was inspired by the Unified Modelling Language (UML) and 4+1 model for software architecture and searched for a simpler way to describe software systems. These ‘heavier’ methodologies didn’t play as well with the agile movement, which was quickly gaining popularity in the 2000s.
❓What does the C4 model solve?
Spaghetti diagrams, inconsistent notation, and duplicate objects to maintain — we’ve all encountered these scenarios when creating architecture diagrams. With a collective shift towards less formal documentation practices, we’ve swung far too much towards embracing poor documentation. Too much documentation can get in the way of building, but no documentation can be just as problematic.
Informal software diagramming is common practice — Source
Whether you’re struggling to document your architecture consistently or haven’t documented anything at all, the C4 model can help bring light structure to your documentation practice to make informed design decisions.
With the C4 model, you can:
- Develop a shared language for communicating your software architecture
- Create consistent diagrams that draw from the same foundational model
- Understand different levels of detail in your architecture, from high to low
- Focus on thinking about your architecture instead of overly complex methodologies
📋 What is it?
The C4 model is a lightweight approach to describing software architecture.
It mainly consists of 2 things:
- A simple set of abstractions to describe your architecture
- 4 core diagram types to visualize these abstractions in a hierarchy
Let’s break these down into more detail 👇
Abstractions
Making sense of complexity is something humans have been doing for centuries with the help of abstractions. From numbers to words and money, they help us capture the essence of detailed concepts in a way everyone can understand.
In software engineering, an abstraction is a way of generalizing complexity (usually code) into something more understandable. It doesn’t replace the need to understand code, but it speeds up alignment and ideation when your system grows in complexity. The C4 model has a simple set of abstractions to describe software systems.
🧍 Person
- The end-user who uses the systems
- Examples: Customer, admin user, or employee
🏢 System
- The highest level of abstraction in the C4 model that delivers value to end users. Often owned by a development team
- Examples: IcePanel is our internal system, Stripe is an external system
📦 Container
- The applications and data stores that make up a system. These are independently runnable/deployable. (Not to be confused with Docker)
- Examples: API service, Front end application, Image bucket
🧩 Component
- The building blocks, modules, or controllers that make up the container
- Examples: Authentication module, payment card validator, user table in a database
Hierarchical diagram types
The C4 model organizes diagrams in (you guessed it) 4 levels. Each diagram level contains a specific scope of abstractions suitable for different audiences.
Diagram types with abstraction levels in the C4 model
1️⃣ Level 1 — Context diagram
What is it: This is the highest-level diagram that gives an overview of core systems and actors
Who is the audience: Anyone who needs to understand how your system works at a high level. Appropriate for technical and non-technical audiences (architects, developers, product and business)
Scope: Actors, systems (internal and/or external)
2️⃣ Level 2 - Container diagram
What is it: A zoomed-in view of a system showing deployable/runnable objects and their relationships with one another
Who is the audience: Mostly technical people (architects, developers) or technically fluent product/business people
Scope: Actors, other systems, containers (apps and stores)
3️⃣ Level 3 - Component diagram
What is it: A zoomed-in view of a container showing the building blocks that make it run
Who is the audience: Technical people (architects and developers)
Scope: Actors, other systems, other containers, components
4️⃣ Level 4 - Code diagram
What is it: Usually in the form of UML class diagrams. Rarely done in practice and can ideally be autogenerated from the actual code
Who is the audience: Technical people (architects and developers)
🏁 Next up
The C4 model is a more modern take on software documentation. With it, you can quickly and consistently create different views of your architecture for different audiences. In the next article, we’ll discuss the key differences between the C4 model and UML, one of the most popular modelling languages in the last twenty years.
