Diagrams with C4 Model


This post is for everyone who draws computer pictures for a living…

The genesis for this post came from a comment on the diagrams-as-code post (via LinkedIn) that called out the C4 Model[1]:


I hadn’t heard of C4 Model before so I decided to check it out. A first look at the C4 Model web site piqued my interest – the philosophy behind it resonated and C4 Model diagrams have a more modern look when compared to standard UML.

Here’s an example from the c4model.com site:


The modern fresh look of C4 Model diagrams. Example diagram from C4Model.com[2]

This raises the question: Do aesthetics matter in IT diagrams? I have to admit I find UML diagrams to have a similar level of aesthetic appeal as brutalist architecture[3]:

How a UML diagram would look as a building – blunt slabs of Brutalist Architecture

Sure, there is the benefit of familiarity – a brutalist building is unmistakably a building, just as a UML diagram is unmistakably an IT diagram – but the sheer ugliness does not engender likability, and that can be an important attribute when you want your audience to show an interest in your diagram.

So, perhaps C4 Model can help if we need diagrams that need to appeal to a wider audience?

Using an Architectural Kata

To put the C4 Model to the test, we use an architectural kata[4] – a training exercise – of a simple e-commerce site that sells horrendous hats:


The Architectural Kata: Horrendous Hats Inc. bringing horrible head-wear to the masses

Don’t get hung up on the tech choices in following diagrams, they’re just an example. Also, note the following diagrams are generated from PlantUML code, using the extension library for C4 Model, and some of the visual appeal of C4 model diminishes because of the implementation – click captions for source PlantUML code.

The Four C’s

The C4 Model is built around the simple philosophy of separating views of the IT stack into just 4 descending hierarchical layers of abstraction, all starting with the letter C (hence the C4 name[5]).


C4 Model Views – A Representative View


A context diagram is the highest level view in C4 Model, where the system is abstracted to a simple rectangle in the middle of the diagram, surrounded users and other systems. We can see how the system interacts, free from detail of how it works. This type of diagram is a great starting point for someone unfamiliar with the system and also works in a top-down architecture approach as a starting point for green-field concepts.

Here we see the context diagram for our online hat retailer:



Context Diagram for Horrendous Hats Digital Presence

This context diagram helps us see that Horrendous Hats Company needs two systems to be able to fulfil its promise of selling truly awful hats to the masses; an e-commerce system that displays the wares to potential customers and allows them to order and pay. Secondly, a fulfilment system is needed to manage stock and sends out orders. C4 Model proving it’s worth already!


The second ‘c’ is for container, and it’s not the type popularised by Docker. A container diagram breaks apart the system box into ‘containers’ that represent things that execute code or store data, such as applications, databases and file systems.

Many things in life are hierarchical, with layers that expose ever-increasing detail, and this is where we go after the C4 model context diagrams – we need to choose what to drill down into. In this example we choose the eComm (e-commerce) System for a container diagram, however to document the whole solution a context diagram should be done for the fulfilment system too.

Here we zoom in on the eComm System from the above diagram, expanding it to show the ‘containers’ within:


Container Diagram for eComm System

C4 Model says that a microservice is a container grouped with its data, however in the above diagram the data is shown separately. Perhaps the databases should be folded into their respective containers? I don’t have a strong view on this.


The third ‘c’ is for component. These are logical groupings of code behind an interface that aren’t separately deployable. We’re deep into the detail now. Let’s drill into the shopping app container showing components within:




Component Diagram for Shopping Application

The component view helps us work out the major code areas (components) required for this ‘container’. We separate out responsibilities for API authentication/routing from business logic (the service) from data models.


Code diagrams drill into a particular component. I’m omitting a code diagram example as I don’t believe it would add much since it is just a UML class diagram, and could be auto-generated from the code.

Diagrams-as-Code with C4 Model

It is possible to use C4 Model diagrams-as-code in PlantUML, thanks to the efforts of Ricardo Niepel (see: https://github.com/RicardoNiepel/C4-PlantUML) and others. Most of the C4 Model diagrams in this post are generated using this extension to PlantUML. A current aesthetic limitation of PlantUML is that the people have no heads [6]

Supplementary Diagrams

There are also 3 types of supplementary diagram specified by C4 Model:

System Landscape Diagram

This type of diagram looks wider than the context diagram and would be useful in a large enterprise, but less so for our hat-slinging start-up, so not included in this blog. Look it up if you’re interested.

Dynamic Diagram

The dynamic diagram is based on a UML communications diagram and shows a sequence of steps between components. It appears to assume a linear flow with no branching. On reflection I think I’ll stick with UML, either a sequence or activity diagram or go for a bog-standard flow chart with swim lanes, as I feel they would be more effective at communicating steps/flow in a process, but still useful to have this type of diagram available for simple use cases.

Deployment Diagram

This is where we start to take a nod to the world of infrastructure. It is a simplified version of the UML deployment diagram and starts to show the relationship of the system with the infrastructure underpinnings.

It uses nested deployment nodes to wrap around the previously defined containers to show relationships to what the containers run in and where.

To be honest, the deployment diagram format doesn’t meet my needs for describing infrastructure, as it doesn’t allow for detailing around technical attributes that may affect concerns, such as availability. Also I don’t think it would provide enough information to build or deploy a full distributed system, but your mileage may vary.

Kata Result

For me, the kata (trying out C4 Model against a fictional situation) helped to better understand the nuances of using C4 model that I would have missed had I just read the official web page. Things I discovered from the kata exercise:

  • The top-down approach to architecting the system where progressive layers drew out more technical detail, but not before it was required, was beneficial. It helped to lay out the main areas of the system before going into tech choices. It also provided a good model for going up and down the levels of abstraction as different considerations came to light
  • Labelling lines (relationships) to describe their purpose was challenging, but beneficial
  • It highlighted to me the sprawl of diagrams that are needed as you work down from the top of the pyramid
  • Perhaps ‘container diagram‘ and ‘component diagram‘ could be pluralised to ‘containers diagram‘ and ‘components diagram‘ respectively to avoid confusion as to what the dashed grey box represents in them, but this is a minor gripe.
  • I didn’t find benefit in the supplementary diagrams; however they could be useful in other cases.
  • Having a data model backing the diagrams would be good to prevent lots of repetitive work changing words in multiple diagrams… more on this now:

It’s all about the Model

For smaller systems it may be fine to manually code or draw the diagrams, but for larger systems it would be advantageous to have a tool that allowed the various elements (i.e. people, systems, containers, components etc.) and relationships (i.e. connecting lines) to be stored in programmatic form so they could be referenced in diagram generation and have a single source of truth. The pyramid structure of C4 Model potentially leads to a plethora of diagrams and failure to abstract wording such as element descriptions and relationship labels breaks the DRY (don’t repeat yourself) principle resulting in lots of manual work to keep diagrams in sync when changes are made.

C4 Model can be modelled in multiple free and paid-for architecture packages including Structurizr, Archi and Sparx Enterprise Architect. Your correspondent didn’t get around to trying C4 Model out in any of these packages – if you do then please let me know how it went in the comments.

The FC4 Framework looks interesting too but at the time of writing Simon Brown, creator of C4 Model, has announced he’s dropping support for Structurizr Express on which it relies for rendering. Looks like there are plans afoot to move to an alternative rendering engine.

Potential Objections

C4 Model is of course not perfect (what in life is?). Here are some potential objections to consider:

  • C4 Model is opinionated about diagram types etc. (but not opinionated about the tech choices). This may be constraining in some circumstances.
  • Some say it does not promote reuse through interfaces/APIs, however I don’t agree with this sentiment as containers (the C4 type) can become reusable microservices[7]
  • C4 Model is not an official standard (although maybe this is a blessing?)
  • It is easy to accidentally transpose the four C’s due to their similar naming and the different usage of the term ‘container’ can lead to confusion
  • The PlantUML extension for C4 Model does not stick faithfully to the C4 model. The people are lacking the circle for the head and boxes do not have rounded corners making for less pleasing aesthetics. Also, the layout algorithm is still woeful once beyond a relatively small number of elements and relationships (a wider issue with PlantUML).

Wrapping it up

I found C4 Model to be a simple, aesthetically-pleasing and effective way to create diagrams in our modern time-poor world. It is more than just an aesthetic improvement over full UML – I found the simple hierarchical structure to be useful for architecting solutions, whereas the plethora of UML diagram types would likely have been less intuitive. The simplicity would definitely help with adoption into cross-discipline product teams.

C4 Model doesn’t cover all use cases and isn’t backed by a global standards organisation; however it seems like a good fit for software development design and implementation projects. C4 Model is independent of the tool used to model, build and display the diagrams, which is a good thing as it brings choice, but does require investigation and decisions to be made. Perhaps it would work best if not treated as a restrictive standard to comply with, but more as a framework that can help produce readable diagrams with the right levels of abstraction. To that end, I’d suggest for use in a team to make a cut-down version of the checklist https://c4model.com/review/ and publish some examples/templates for people to start from. Consider using PlantUML for diagram code source control and embed diagrams in a Wiki such as Confluence.

So, why not shake off the shackles of brutalist UML diagrams and start creating eye-pleasing C4 Model diagrams that add value and connect with your audience?


[1] From LinkedIn, comment cropped to just this topic, I’ll leave the poster anonymous

[2] Diagram sourced from https://c4model.com/ by Simon Brown and licensed under Creative Commons Attribution 4.0 International License

[3] For more on the sheer horror of brutalist architecture see Wikipedia: https://en.wikipedia.org/wiki/Brutalist_architecture

[4] An architecture kata is a method of practicing IT architecture using fictional use case, see: http://nealford.com/katas/

[5] Beware of other meanings for the name; searching for ‘C4’ may put you on a watch list somewhere…

[6] See issue on user aesthetics at https://github.com/RicardoNiepel/C4-PlantUML/issues/45

[7] A software engineer raises his objections to C4 Model: https://www.quora.com/Have-anybody-tried-C4-software-architecture-model-for-real-projects

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s