The C4 Software Architecture Model

The Agile Manifesto prescribes that teams should value working software over comprehensive documentation. This doesn’t mean that we should not create documentation; it just means we should create documentation that provides value and at the same time does not hinder the team’s progress. We can achieve this using C4 architecture model. It is a static model, that provides an easy way to communicate the design of the system to all involved, and also brings a natural narrative for exploring the architecture of a software solution. Starting from the highest level (what is the system and how does it provides value to the business), it drills into the details, until the very low level of functionality.

It could be something to next car presentation, showing the relevant details from outside to inside:

Source: Wired article (link)

This architecture model has been created by Simon Brown, and you can find more details and live presentations on his website simonbrown.je.

Why Such Architecture Model?

The C4 model is a hierarchical way to think about the structures of a software system. Why such a model would be needed, since the existence of UML, or 4 + 1 architecture views (Wikipedia link) and the others? I see the following advantages:

• Makes the diagrams easy to read – Usually the diagrams that design a software system are part of the context in the documents, and it is harder to get the full meaning, without reading the full specification. C4 Models encourage to write succinct description text within the diagram, making them easy to comprehend and use, even outside of a documentation. This gives a chance to be easier used by other members of the team.
• It has a role of zoom in / zoom out, providing the different amount of details, better suited to different persons / roles involved in the project. It starts from a context or general diagram, and goes into the details of containers (one or more containers such as web applications, mobile apps, standalone applications, databases, file systems, etc.). Each of the containers has one or more components, which in turn are implemented by one or more classes.
• Reduces the gap between design and actual implementation – Diagrams could be made in any tool. Even so, generating them using few lines of code, it makes possible to easier maintain them along the way the software product is developed. Here is the tool – structurizr.com

Arhitectural Kata

To try this model, I would propose to start from a simple specification, initially designed for an architectural kata sessions. In this article, I would be focused more on the way we graphically represent the system(s), rather to discuss how effectively the system is designed. In some parts, other technology selections would make more sense.

A national sandwich shop wants to enable “fax in your order”, but over the Internet instead.

Users: millions+

Requirements: Users will place their order, then be given a time to pick up their sandwich and directions to the shop (which must integrate with Google Maps); if the shop offers a delivery service, dispatch the driver with the sandwich to the user; mobile-device accessibility; offer national daily promotionals/specials; offer local daily promotionals/specials; accept payment online or in person/on delivery.

Source: Architectural katas – Neal Ford

C4 Model - Diagrams

1. Context diagram
2. Container diagram
3. Component diagram(s)
4. Class diagram(s)

Context Diagram

“Draw a simple block diagram showing your software system as a box in the centre, surrounded by its users and the other software 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.”

From “Software Architecture for Developers – Volume 2 – Simon Brown”

This diagram provides the big picture, and it answers to the following questions:

1. What is the software system that we are building?

   It presents the 3 systems to build (external, to the public users; internal, for order processing; and one optional for delivery management).

2. Who is using it?

   It presents 8 types of users, with a short description of their role (e.g. mobile user, etc.), as well as their actions (e.g., place an order, etc.).

3. How does it fit in with the existing environment?

   Here are included other systems to interact. It could be internal to the organization (e.g. ERP, CRM, etc.), or external (e.g., Google Maps service)

These diagrams also reflect the approach, via dependent systems – example: a serverless architecture would be represented in another way.

Note: The diagram is just a sample, and it does not reflect a real product. Different approaches could be considered. What is more important here, is to see the diagrams with a lot of information included, not requiring extensive documents to explain them.

Second Part, Container Diagram

This is a simple, high-level technology focused diagram. It is a high-level shape of the software architecture and it shows how responsibilities are distributed across it. The diagram answers the following questions:

1. What is the overall shape of the software system?
2. What are the high-level technology decisions?
3. How are responsibilities distributed across the system?
4. How do containers communicate with one another?
5. As a developer, where do I need to write code in order to implement features?

Note: The diagram is just a sample. Different technologies and approaches could be used. Maybe the technology stack used here is not what would you prefer. Still, having the full system (or subsystem, in case it is big) displayed on a page (A3 / A4) could bring clarity and make different decisions easier to take.

Even for very big systems, we could draw similar diagrams. Here is an example reflecting StackOverflow architecture (from Nick Craver – 2016 Architecture), which could be converted to a Container diagram. StackOverflow is a a system with 1.3 billion page views per month.

Third part, Component Diagram(s)

The next step would be to zoom in and decompose containers further, to show the inside components. This set of diagrams should answer the following questions:

1. What components/services is the system made up of?
2. It is clear how the system works at a high-level?
3. Do all components/services have a home (i.e., reside in a container)?

At this level, it would not be important to make all these diagrams from the beginning. These would be written as soon as certain components are developed. Then, once the components will be updated, the diagrams will reflect the changes.

Note: Maybe the components you would choose would be different. They could be made in other ways comparing with what is presented. Still, having the option to always have at hand the documents, and make zoom in / out using a document system such Confluence, or using Structurizr tool gives a lot of power to the team(s) that actually build the product.

Last Part, Class Diagrams

To keep it simple, diagrams at this level would be used just to illustrate specific details. These are standard UML diagrams and they could be generated with many many tools. Here is a small sample, starting from a sample provided by LucidChart tool (the same I have used to display also the other diagrams):

Common Understanding and Knowledge

Being used by one or more teams that build or maintain a product or software project, this model could generate a common understanding. Using the same diagrams, the team members start using the same vocabulary, giving a better chance to relate each other’s knowledge and expertise. In the end, this is a core advantage of the successful teams.

More on Visually Communicating the Architecture

You can find a full presentation here, made by Simon Brown, who created this model: Vimeo video

Give It a Try

Whenever you start a new project, try to make at least one context diagram and then a container diagram. Drawing them on paper, together with the other team members, could bring something new in the conversation, and make it easier to explain the view of the system.

*The questions associated with each diagram are taken from Software Architecture for Developers – Volume 2.