⚡ Tl;dr
- Defining systems in your business within the C4 model can be difficult when starting to use the C4 model
- Taking time to step back and work on this as a team within your organization can create a consistent language faster
- Follow these tips to define your systems
🚀 Let’s kick-off
The C4 model is a powerful tool that uses simple abstractions and a levelled diagramming approach to describe software architecture. This lightweight approach to visualizing software architecture keeps your documentation agile as you develop your solutions - awesome, right?!
One of the first steps when adopting or trying out the C4 model, either on your own or with a few team members, is to define your layered abstractions in the context of your organization/ecosystem.
Having a definitive agreement on these abstraction layers is critical to getting started because everyone should understand what each abstraction means and how to use them. This is an important step that shouldn’t be missed; skipping it is like baking a cake without a list of ingredients and instructions - a recipe for a mess.
The first step and most important is defining your top-level abstraction: Systems.
📦 What is a system?
On the c4model.com website, a system is clearly defined as:
“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). In many cases, a software system is “owned by” a single software development team.”
From c4model.com
It’s easy to scan this and miss the key parts that are crucial to defining your systems. It’s a simple abstraction and important to get right to make the most of the C4 model, but the outcome often depends on your organization. The most important words of this definition are:
Software system: Something that delivers value to its users, in many cases owned by a single software development team.
We reached out to Simon, the creator of the C4 model, on Twitter to ask his advice on how he helps the teams he works with when defining their systems. He responded with:
Mapping your systems to the teams that build them is a good first step to defining your internal software systems. If you’re a small/medium-sized business you will likely have few systems. Larger enterprises will likely have more systems that make up the overall ecosystem.
You may also have external software systems that you depend on to run some of your services, for example:
- Payment providers - i.e. Stripe, PayPal
- Metrics & analytics tools - i.e. Mixpanel, Google Analytics
- Monitoring tools - i.e. Splunk, Datadog
- Authentication - i.e. Auth0, Okta
🧑🏫 Workshop to define your systems
To ensure consistency in your language when talking about and visualizing your software architecture, we recommend ensuring everyone is on the same page about the definition of your software systems. Get your lead tech decision-makers and product people in the same place when discussing this step. A huge benefit of the C4 model is the consistent language, resulting in everyone on your team understanding the same meaning when they say: system, container (apps/store), and components.
By taking your time here to step back before going too deep into the visual part of the C4 model, you ensure there is an agreement on abstraction before visualizing that - this will avoid extra re-work being done later on. A workshop is a worthy time investment here in defining systems that make sense for your organization. This should only take 20-30 mins.
What you’ll need:
- 👥 The right people - Lead tech decision-makers and product people
- 🗒️ Sticky notes
- ✏️ Pens - ideally one each
- 🧑🏫 A surface for sticky notes
- ⏰ A timekeeping device
Define your systems workshop steps:
Step 1. Gather the right people
(the most time-consuming part)
Get the right people in the same place (physical or virtual). This will likely look like:
- Architects
- Tech leads
- Developers
- Product leads
Assign 1 person as the timekeeper and workshop facilitator.
Have a copy of the c4 model definition visible to everyone:
Step 2. Define your systems
(5-20 mins)
Here are the 2 common methods we see teams using to define their systems. (maybe try both)
Bottom-up (10-20 mins)
Approach: Start with your applications or services and group them logically - These groupings are your systems - internal or external.
-
Introduce the software system definition
-
⏰ Set the timer to 10 mins
Start individually writing core applications in your business on sticky notes - don’t worry about duplicates -
⏰ Set the timer to 5 mins again
As a group, start grouping applications logically -
Name the logical groups based on the value each grouping provides
Top-down (5-10 mins)
Approach: Start by looking at the value created by the business to a group of 1 or more people. These can be internal or external
-
Introduce the software system definition
-
⏰ Set the timer to 5 mins
Start individually writing the systems you believe best describe how your products or services exist today -
⏰ Set the timer to 5 mins again
Discuss common themes and collaboratively agree on your systems
Step 3. Test your definition
(5 mins)
⏰ Set the timer to 5 mins
- Take the first systems you’ve created and write [System] somewhere.
- Put them up on a whiteboard (physical or virtual).
- Add a user of your systems with the tag [Person].
- Connect your systems with labelled lines with the main use cases each system/person is dependent on the rest.
Step back and see if you understand what is going on as a group. This can be tidied up later.
We created some template C4 stickies to help with this stage, focused on the C4 model. - Comment if you want some 💬
Step 4. Do others understand?
Send the definition and example visual to your business/product-level stakeholders to see if they understand what you’ve drawn - remember this should be understandable to all of your audiences (via instant message/email).
Huzzah! You’ve completed the first step together.
🏁 To wrap up
Defining your Systems when getting started with the C4 model can be hard to work out without taking a step back and looking at the overall picture. Workshopping as a group helps to create a consistent language amongst the people you work closely with and the rest of your organization. Gather feedback from others before diving into the more detailed levels of the C4 model.
Stay chill 🧊
