⚡ Tl;dr

• Diagrams are crucial in visually communicating software systems to technical AND non-technical people.
• Diagramming without a structured approach allows too much flexibility and yields ambiguous or confusing outcomes.
• The C4 model gives a lightweight methodology for visual and verbal communication of systems, for more efficient conversations.

🚀 Let’s kick-off

Communication is arguably the most critical and defining skill in great software development teams. Great communication allows us to understand everything we need to move forward and get the work done. It’s crucial to understand how our system(s) work today, the choices we’ve made that are empowering/constraining us, where we’re going next, and how our system solves our customer’s pain. However, communicating how our systems technically work and the choices we’ve made as a team are hard to get right consistently and often yields various degrees of helpfulness in the outcome. Finding a balance between “understandability" (by humans) and “correctness" (the code) is a complex undertaking, especially in cross-functional teams, where you’re explaining to a mixed group of technical and non-technical people.

Our systems are also (mostly) moving towards a more distributed architecture which adds more complexity to the communication of how they work. Trawling through technical specs, diagrams found sporadically within internal wiki pages, reviewing an online whiteboard conversation you had a month ago, slack threads and unpicking code to mentally connect the dots, have become a living nightmare for a lot of us. It’s hard to know precisely what is true without consensus or asking several people before deciding how to move forward.

“Working software over comprehensive documentation" says the agile manifesto, which a lot of teams took as “great … no need to waste time on creating docs anymore". But we still have conversations all the time and those decisions get lost without ANY documentation. So freeform ad-hoc artifacts start appearing, which are later on used as a starting point for further conversations. Those starting points, that were once maybe true, become out of date quickly when developing at speed, and so conversations are based on untrue artifacts, leading to unfortunately costly misunderstandings either in time or money.

In this article, we’ll explore how to get your whole team on the same page about your software architecture design and allow you to have more efficient conversations about how your systems work. A lightweight approach to visualizing and conversing about your design - the C4 model.

🖼️ Diagramming architecture

Why is the way we diagram software still a topic of discussion?

Software systems are complex to understand. Visually communicating those complexities using abstractions helps us to share and map in our heads how our systems work. “A picture is worth a thousand words" is as old as time, but still holds true today, no matter where you are in the world and in software development, diagrams are the “picture" we use to help explain the complexities within our systems. These diagram visuals take many forms, from unstructured drawings of boxes and lines on a whiteboard, to fully documented digital diagrams, sometimes taking the form of a Unified Modeling Language (UML) component, class, sequence, etc. diagram. (although from discussions we’ve had, this seems to be dying if not a dead practice in modern agile teams)

Most teams run conversations using a multitude of visual artifacts somewhere in the middle of structured and unstructured, with varying degrees of usefulness. The rise of diagramming tools and online whiteboards has given us an overwhelming level of flexibility, which in turn makes the outcome of visuals difficult to understand as there are too many choices. This is known as Hicks law: "The time it takes to make a decision increases with the number and complexity of choices." - think about how long it takes to choose a film on Netflix…

Diagram creators have the choice of hundreds of icons, shapes, styles, and millions of colours that are often unlabeled. These choices mean the creator spends a long time making the decisions on what to add to a diagram AND the end user (the viewer of the diagram) has to work hard to unpack and understand what they’re looking at, often being punched in the face with colour choices when they first view it (you’ve seen the diagrams).

"Someone opening a Visio diagram found in a deeply hidden folder on Confluence that’s 6 months out of date."

There is too much choice and a lack of consistency in both the language and visuals that meet the requirements to simply explain how our systems work whilst we remain agile as a team; as such birthed the C4 model.

🦸 The C4 model to the rescue!

Let’s quickly talk about what the C4 model is.

In its simplest form the C4 model is a lightweight approach to describing system architecture and consists of 2 things:

1. A simple set of abstractions to describe your architecture
2. 4 core diagram types to visualize the abstractions

The C4 model was created by Simon Brown after observing the inefficiencies in visually and verbally communicating architecture. The 4 diagram levels that give the C4 its name act as a visual map of your system(s) with defined levels of abstraction. These abstraction levels are designed for your different audience types from non-technical high level to developer-focused low level - remember diagrams are not just for technical people. The simple set of abstractions ensures everyone is talking the same language when communicating about system design - reducing confusion about terminology.

🖼 Abstractions

(summarised from c4model.com/#Abstractions)

The first of the 2 things that make up the C4 model. These are the simple set of abstractions to use when describing how your software or system works.

🧍 Person

The end user who uses the systems.

E.g. customer, an admin user

🏢 System

The highest level of abstraction that delivers value to end users. Often owned by a development team.

E.g. IcePanel is our system, SendGrid is an external system we utilize

📦 Container

The applications and data stores that make up a system. These are independently deployable. (Not to be confused with Docker)

E.g. API service, Front end application

🧩 Component

The building blocks/modules that make up the container.

E.g. Authentication module, payment card validator

🧑‍🎨 Diagram types

The second part to the C4Model. The visual representations of how your system works, using the abstractions above, which are designed for specific audiences.

Level 1 - Context diagram

What is it: This is the highest level of abstraction. Showcase the basics of how your users interact with your system to get value.

Who is the audience: Anyone that needs to know how users interact with your solution. Technical and non-technical (Architects, developers, product and business)

Scope: Persons, systems

Level 2 - Container diagram

What is it: A zoomed-in view of 1 system showing the running objects inside.

Who is the audience: Mostly technical people, more technically minded product/business people also get value here (Product owners, business analysts etc.)

Scope: Persons, other systems, containers inside the zoomed-in system

Level 3 - Component diagram

What is it: A zoomed-in view of 1 container showing the building blocks that make it run.

Who is the audience: Technical (Architects and developers)

Scope: Persons, other systems, other containers inside the same system, components

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 (Architects and developers)

There are supplementary diagrams to fill in information gaps by showcasing views such as deployment information, sequence of events and how systems interact at a higher level.
These can be found here: c4model.com/#SupplementaryDiagrams.

For a more detailed explanation of the C4 model go to c4model.com

🧐 How does C4 help?

The C4 model is designed for simple communication of complex systems, perfect for cross-functional teams, where communication is rapid and varied in the technical language used. Most teams gain tremendous value in the top 2 levels (Context and Container), providing a single, simple view of how the systems work. Having consensus on the abstractions in your design helps to run more efficient conversations and in turn more confident decision-making. Product and business people gain value from understanding how the users use the service you provide at the context level and new developers can quickly see the main flows that you’re system provides. Zooming in helps define the processes going on at more technical levels, without having to dive into the code and unpick it yourself.

It’s important to think of the C4 model as a methodology to use in day-to-day visual AND verbal communication. This lightweight structure and approach enables your team to be confident in decision-making by talking in the same language and having a common understanding of the design. For best results, it should be used anywhere you talk about your system design, such as in ad-hoc conversations, larger-scale meetings and full documentation processes.

👥 Who should use C4

At IcePanel we have seen how the C4 model empowers teams of all sizes from startups to scale-ups to enterprises. This consistent language and layered approach can be picked up and used quickly. You can even start right now with that Level 1 context of your system, using nothing but a pen and piece of paper to practice.

If you or your team members are finding it hard to communicate your system with clarity or you’re frustrated with the various styles of diagrams that get created, maybe start with the abstractions at a higher level to show the context; give the C4 model a go in your next conversation. There is great power in simplicity.

It’s also worth noting that diagrams on their own may not scale well … so using modelling to draw out these diagrams helps with long-lived documentation. When changes inevitably happen, your model object updates can be synced across multiple diagrams at once - check out our modelling vs diagramming article for more on that.

🛠️ Top 3 C4 model tools

Although a pen and paper or whiteboard are all you need for short-term conversations, there are tools designed to directly support the C4 model for long-lived documentation. These come in multiple product types depending on personal and/or team choice. We’ll just briefly cover the top 3 options in this article for you to check out.

1️⃣ Visual modelling tooling - IcePanel.io

Best for: Team collaboration, UX/UI, quick visual creation of a model

2️⃣ Text-based modelling - Structurizr

Best for: Technical people, diagrams-as-code

3️⃣ Text-based diagramming- C4-PlantUML

Best for: Small discussions, diagrams-as-code

🏁 To wrap up

So… should you use the C4 model for your system architecture design? If you’re looking for a better, quicker and more accessible way to explain how your systems work, then yes. Of course, we are biased that the C4 model is great, but there is one way you can choose for yourself - give it a go next time you find yourself or others are confused by how your system works.

Stay chill 🧊

ℹ️ Infographic

Download here