The C4 model for software architecture
Context, Containers, Components and Classes (or Code)
Background and history
Creating software architecture diagrams is something of a lost art. Simon Brown has been running software architecture training courses for a number of years, part of which is a simple architecture kata where groups of people are asked to design a software solution and draw some architecture diagrams to describe it. Based upon the anecdotal evidence from training over 10,000 people in more than 25 countries, software architects and developers struggle with how to communicate software architecture. Even today, the majority of the diagrams from the initial iteration of the architecture kata are typically created using an ad hoc “boxes and lines” notation with no clear notation or semantics.
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.
Like source code, Google Street View provides a very low-level and accurate view of a location.
Navigating an unfamilar environment becomes easier if you zoom out though.
Zooming out further will provide additional context you might not have been aware of.
Different levels of zoom allow you to tell different stories to different audiences.
In order to create these maps of your code, we first need a common set of abstractions to create a ubiquitous language that we can use to describe the static structure of a software system. The C4 model considers the static structures of a software system in terms of containers, components and classes (or code). And people use the software systems that we build.
However you think about your users (as actors, roles, personas, etc), people are the various human users of your software system.
A software system is the highest level of abstraction and describes something that delivers value to its users, whether they are human or not. This includes the software system you are modelling, and the other software systems upon which your software system depends (or vice versa).
A container represents something that hosts code or data. A container is something that needs to be running in order for the overall software system to work. In real terms, a container is something like:
- Server-side web application: A Java EE web application running on Apache Tomcat, an ASP.NET MVC application running on Microsoft IIS, a Ruby on Rails application running on WEBrick, a Node.js application, etc.
- Client-side desktop application: A Windows desktop application written using WPF, an OS X desktop application written using Objective-C, a cross-platform desktop application written using JavaFX, etc.
- Mobile app: An Apple iOS app, an Android app, a Microsoft Windows Phone app, etc.
- Server-side console application: A standalone (e.g. "public static void main") application, a batch process, etc.
- Microservice: A single microservice, hosted in anything from a traditional web server to something like Spring Boot, Dropwizard, etc.
- Database: A schema or database in a relational database management system, document store, graph database, etc such as MySQL, Microsoft SQL Server, Oracle Database, MongoDB, Riak, Cassandra, Neo4j, etc.
- Blob or content store: A blob store (e.g. Amazon S3, Microsoft Azure Blob Storage, etc) or content delivery network (e.g. Akamai, Amazon CloudFront, etc).
- File system: A full local file system or a portion of a larger networked file system (e.g. SAN, NAS, etc).
- Shell script: A single shell script written in Bash, etc.
A container is essentially a context or boundary inside which some code is executed or some data is stored. And each container is a separately deployable/runnable thing or runtime environment.
The word "component" is a hugely overloaded term in the software development industry, but in this context a component is simply a grouping of related functionality encapsulated behind a well-defined interface. If you're using a language like Java or C#, the simplest way to think of a component is that it's a collection of implementation classes behind an interface. Aspects such as how those components are packaged (e.g. one component vs many components per JAR file, DLL, shared library, etc) is a separate and orthogonal concern.
Visualising this hierarchy of abstractions is then done by creating a collection of Context, Container, Component and (optionally) Class (or Code) diagrams. This is where the C4 model gets its name from.
Level 1: System Context diagram
A System Context diagram is a good starting point for diagramming and documenting a software system, allowing you to step back and see the big picture. Draw a diagram showing your system as a box in the centre, surrounded by its users and the other systems that it interacts with.
Detail isn't important here as this is your zoomed out view showing a big picture of the system landscape. The focus should be on people (actors, roles, personas, etc) and software systems rather than technologies, protocols and other low-level details. It's the sort of diagram that you could show to non-technical people.
Scope: A single software system.
Primary elements: The software system in scope.
Supporting elements: People and software systems directly connected to the software system in scope.
Intended audience: Technical and non-technical people, inside and outside of the immediate software development team.
Level 2: Container diagram
Once you understand how your system fits in to the overall IT environment, a really useful next step is to zoom-in to the system boundary with a Container diagram. A "container" is something like a web application, desktop application, mobile app, database, file system, etc. Essentially, a container is a separately deployable unit that executes code or stores data.
The Container diagram shows the high-level shape of the software architecture and how responsibilities are distributed across it. It also shows the major technology choices and how the containers communicate with one another. It's a simple, high-level technology focussed diagram that is useful for software developers and support/operations staff alike.
Scope: A single software system.
Primary elements: Containers within the software system in scope.
Supporting elements: People and software systems directly connected to the containers.
Intended audience: Technical people inside and outside of the immediate software development team; including everybody from software developers through to operations and support staff.
Level 3: Component diagram
Next you can zoom in and decompose each container further to identify the major structural building blocks and their interactions.
The Component diagram shows how a container is made up of a number of "components", what each of those components are, their responsibilities and the technology/implementation details.
Scope: A single container.
Primary elements: Components within the container in scope.
Supporting elements: Containers (within the software system in scope) plus people and software systems directly connected to the components.
Intended audience: Technical people within the software development team.
Level 4: Code
Finally, you can zoom in to each component to show how it is implemented as code; using UML class diagrams, entity relationship diagrams or similar.
This is an optional level of detail and is often available on-demand from tooling such as IDEs. This level of detail is not recommended for anything but the most important or complex components.
Scope: A single component.
Primary elements: Code elements (e.g. classes, interfaces, objects, functions, database tables, etc) within the component in scope.
Intended audience: Technical people within the software development team.
Once you have a good understanding of the static structure, you can supplement the C4 diagrams to show other aspects.
System Landscape diagram
The C4 model provides a static view of a single software system but, in the real-world, software systems never live in isolation. For this reason, and particularly if you are responsible for a collection of software systems, it's often useful to understand how all of these software systems fit together within the bounds of an enterprise. To do this, simply add another diagram that sits "on top" of the C4 diagrams, to show the system landscape from an IT perspective. Like the System Context diagram, this diagram can show the organisational boundary, internal/external users and internal/external systems.
Essentially this is a high-level map of the software systems at the enterprise level, with a C4 drill-down for each software system of interest. From a practical perspective, a system landscape diagram is really just a system context diagram without a specific focus on a particular software system.
A simple dynamic diagram can be useful when you want to show how elements in a static model collaborate at runtime to implement a user story, use case, feature, etc. This dynamic diagram is based upon a UML communication diagram (previously known as a "UML collaboration diagram"). It is similar to a UML sequence diagram although it allows a free-form arrangement of diagram elements with numbered interactions to indicate ordering.
A deployment diagram allows you to illustrate how containers in the static model are mapped to infrastructure. This deployment diagram is based upon a UML deployment diagram, although simplified slightly to show the mapping between containers and deployment nodes. A deployment node is something like physical infrastructure (e.g. a physical server or device), virtualised infrastructure (e.g. IaaS, PaaS, a virtual machine), containerised infrastructure (e.g. a Docker container), an execution environment (e.g. a database server, Java EE web/application server, Microsoft IIS), etc. Deployment nodes can be nested.
The C4 model doesn't prescribe any particular notation. A simple notation that works well on whiteboards, paper, sticky notes, index cards and a variety of diagraming tools is as follows.
You can then use colour and shapes to supplement the diagram, either to add additional information or simply to make the diagram more aesthetically pleasing.
C4 and UML
Although the example diagrams above are created using a "boxes and lines" notation, the core diagrams can be illustrated using UML with the appropriate use of packages, components and stereotypes. The resulting UML diagrams do tend to lack the same degree of descriptive text though, because adding such text isn't possible (or easy) with some UML tools.
Any notation used should be as self-describing as possible, but all diagrams should have a key/legend to make the notation explicit. This applies to diagrams created with notations like UML, ArchiMate and SysML too, as not everybody will know the notation being used.
Notation, notation, notation
Although the C4 model is an abstraction-first approach and notation independent, you still need to ensure that your diagram notation makes sense, and that the diagrams are comprehensible. A good way to think about this is to ask yourself whether each diagram can stand alone, and be (mostly) understood without a narrative. Here are some recommendations related to notation.
- Every diagram should have a title describing the diagram type and scope (e.g. "System Context diagram for My Software System").
- Every diagram should have a key/legend explaining the notation being used (e.g. shapes, colours, border styles, line types, arrow heads, etc).
- Acronyms and abbreviations (business/domain or technology) should be understandable by all audiences, or explained in the diagram key/legend.
- The type of every element should be explicitly specified (e.g. Person, Software System, Container or Component).
- Every element should have a short description, to provide an "at a glance" view of key responsibilities.
- Every container and component should have a technology explicitly specified.
- Every line should represent a unidirectional relationship.
- Every line should be labelled, the label being consistent with the direction and intent (e.g. dependency or data flow) of the relationship.
- Relationships between containers (typically these represent inter-process communication) should have a technology/protocol explicitly labelled.
If you're interested in using the C4 model or building tooling to support it, here is some information about the basic metamodel.
Elements and relationships
|Container||A software system||
|Code Element||A component||
* All elements in the model must have a name, and that name must be unique within the parent context.
** Relationships are permitted between any elements in the model, in either direction.
Frequently asked questions
C4 and microservices?
Broadly speaking, there are two options for diagramming microservices when using the C4 model.
- Microservices as software systems: If your software system has a dependency upon a number of microservices that are outside of your control (e.g. they are owned and/or operated by a separate team), model these microservices as external software systems that you can't see inside of.
- Microservices as containers: On the other hand, if the microservices are a part of a software system that you are building (i.e. you own them), model them as containers, along with any data stores that those microservices use. In the same way that a modular monolithic application is a container with a number of components running inside it, a microservice is simply a container with a (smaller) number of components running inside it.
Large and complex software sytems?
Even with a relatively small software system, it's tempting to try and include the entire story on a single diagram. For example, if you have a web application, it seems logical to create a single component diagram that shows all of the components that make up that web application. Unless your software system really is that small, you're likely to run out of room on the diagram canvas or find it difficult to discover a layout that isn't cluttered by a myriad of overlapping lines. Using a larger diagram canvas can sometimes help, but large diagrams are usually hard to interpret and comprehend because the cognitive load is too high. And if nobody understands the diagram, nobody is going to look at it.
Instead, don't be afraid to split that single complex diagram into a larger number of simpler diagrams, each with a specific focus around a business area, functional area, functional grouping, bounded context, use case, user interaction, feature set, etc. The key is to ensure that each of the separate diagrams tells a different part of the same overall story, at the same level of abstraction.
C4 and arc42?
The C4 model is compatible with the arc42 documentation template as follows.
- Context and Scope => System Context diagram
- Building Block View (level 1) => Container diagram
- Building Block View (level 2) => Component diagram
- Building Block View (level 3) => Class diagram
C4 vs UML, ArchiMate and SysML?
Although existing notations such as UML, ArchiMate and SysML already exist, many software development teams don't seem to use them. Often this is because teams don't know these notations well enough, perceive them to be too complicated, think they are not compatible with agile approaches or don't have the required tooling.
If you are already successfully using one of these notations to communicate software architecture and it's working, stick with it. If not, try the C4 model. And don't be afraid to supplement the C4 diagrams with UML state diagrams, timing diagrams, etc if you need to.
Change the terminology?
This terminology (context, containers, components and classes) works for many organisations and many types of software. However, sometimes an organisation will have an existing terminology that people are already familiar with. Or perhaps "components" and "classes" don't easily map on to the technology being used (e.g. functional languages often use the terms "module" and "function"). Feel free to modify the terminology that you use to describe software architecture at different levels of abstraction. Just make sure that everybody explicitly understands it.
Here are some collections of example software architecture diagrams based upon the C4 model.
The following resources are recommended if you're looking for more information about visualising software architecture and the C4 model.
This is a recording of Simon Brown's talk at the OpenSlava conference in Bratislava, Slovakia during October 2017 (35 minutes).
This is a recording of Simon Brown's keynote at the Voxxed Days conference in Athens, Greece during May 2017 (60 minutes).
This is Simon Brown's Software Architecture for Developers (Volume 2) ebook, which is available to purchase from Leanpub as an ebook in PDF, EPUB and MOBI formats. It's a short guide to visualising, documenting and exploring your software architecture.
"Visualising software architecture with the C4 model" is a hands-on, 1-day workshop with Simon Brown that focusses on the visualisation and communication of software architecture using the C4 model. The core of this workshop can be based upon a simple case study (an architecture kata) or your own software systems.
It's very likely that the majority of the software architecture diagrams you've seen are a confused mess of boxes and lines. Following the publication of the Manifesto for Agile Software Development in 2001, teams have abandoned UML, discarded the concept of modelling and instead place a heavy reliance on conversations centered around incoherent whiteboard diagrams or shallow "Marketecture" diagrams created with Visio. Moving fast and being agile requires good communication, yet software development teams struggle with this fundamental skill. A good set of software architecture diagrams are priceless for aligning a team around a shared vision and for getting new-joiners productive fast.
This hands-on workshop explores the visual communication of software architecture and is based upon a decade of my experiences working with software development teams large and small across the globe. We'll look at what is commonplace today, the importance of creating a shared vocabulary, diagram notation, and the value of creating a lightweight model to describe your software system. The workshop is based upon the "C4 model", which I 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. Static structure, runtime and deployment diagrams are all covered, so you'll be able to tell different stories to different audiences. We'll wrap up the day by looking at the tooling landscape and diagram automation to keep your diagrams in sync with your source code.
This 1-day workshop will give you some pragmatic, practical and lightweight techniques that you can apply to your work the very next day. You'll learn why most software architecture diagrams are meaningless, how to critique them, how to fix them and how to use the C4 model to create a simple yet powerful set of developer-friendly diagrams to describe software architecture.
Software developers and architects; all levels of experience.
Some experience building software; no laptops needed.
The exact timings are flexible, but most courses are typically 09:00-17:00, with a 20-30 minute coffee break mid-morning and mid-afternoon, plus an hour for lunch.
Slides and handouts
The slides and handouts for the training course are available to download.
Download the full set of slides and handouts (~70MB .zip file)
The pricing model is "per day" rather than "per attendee", based upon location. The class size is flexible; the recommended number of people is between 10 and 30, although previous courses have been run for between 5 and 150 people. From a logistics point of view, all that is needed is a room with a projector and some whiteboards/flip chart paper. This workshop is occasionally run publicly via training providers or conferences but most are private, on-site workshops held directly with organisations.
Please e-mail Simon Brown for more details and pricing.
The following modelling and drawing tools can help create software architecture diagrams based upon the C4 model.
Structurizr is a collection of tooling to help you visualise, document and explore your software architecture. It's an implementation of the C4 model and allows you to create software architecture models using Java/C# and supplementary documentation using Markdown/AsciiDoc.
Structurizr Express lets you quickly create individual diagrams from the C4 model, using a JSON/YAML text format.
The open source Structurizr for Java library allows you to create a software architecture model and export it to the DOT syntax used by Graphviz.
Sparx Enterprise Architect
LieberLieber Software has built an extension for the C4 model, based upon the MDG Technology built into Sparx Enterprise Architect.