Blog Software Development C4 modeling at levels 1 and 2 - moving within a large domain despite documentation gapsC4 modeling at levels 1 and 2 - moving within a large domain despite documentation gaps
Working with complex systems that include many services, integrations and dependencies might be challenging. When such systems are taken over, usually their extensive documentation and business processes are comprehensively described. It also happens that the documentation provided is outdated or incomplete, and the knowledge is kept by authors and domain experts. Read about how we dealt with a C4 implementation for one of our US clients.
Table of contents
In the following article, we will describe how we mapped the domain to effectively enter the system and create useful functionalities meeting the client’s business goals.
The starting point
The system we were supposed to dive into was built by one of the largest e-commerce providers in the US: multiple warehouses, web applications, advanced logistics, handling many marketplaces - all this required modernization and optimization.
So we had documentation, infrastructure diagrams, process diagrams, but some of the knowledge was held by various members of the customer’s organization. We could ask the client’s in-house team and those familiar with client-side processes for regular updates on an existing documentation. Unfortunately this process would be extremely time-consuming, and we wanted to start the product development process as soon as possible.
We decided to take things into our own hands. We started by analyzing the existing documentation, and later we conducted a series of interviews with the people with the most up-to-date knowledge of the system and processes. Then, we mapped the gathered information using a level 1 and 2 C4 diagram. Let’s explain what we mean by that.
What is the C4 model?
The C4 model is a way of mapping architecture, similar to geographic maps. We distinguish between four levels, with each successive level increasingly more detailed than the previous one:
- Context
- Container
- Component
- Code
As in maps, Context is the country level, Container the state and so on. In addition, the blocks in the diagram can be internal (blue, under our control) and external (gray, 3rd party that we integrate with). Add to this:
- Persons that use the system
- Relationships between persons and the parts of the system
And that’s it - a simple tool for mapping complex domains. You can read more about it in the official documentation.
See below examples:
C4 architecture level 1 (Context) & C4 architecture level 2 (Container) of an online banking system.
.
Why is C4 great for accumulating knowledge scattered between existing documentation and employees?
- It is very easy to understand at levels 1 (Context) and 2 (Container) by people without technical knowledge or background. It makes it easy to get feedback on the content and implement possible corrections.
- It can be created relatively quickly - both by synthesizing the current documentation and via live conversations with domain experts.
- It’s a great introduction to even deeper and more accurate domain mapping by Big Picture Event Storming, for example. The C4 output at levels 1 and 2 is a ready input to BPES.
- It is easy to maintain and update with the Diagram as a Code approach from C4 PlantUML, as we will describe below.
Implementation of the solution
As we have already recognized the essence of the problem and the potential solution, it’s time to move on to the implementation.
- A good entry point would be the aforementioned analysis of existing documentation. Starting at the highest level, we identify Persons, Contexts and External Systems and the relationships between them. All based on existing materials.
- Now it’s time for revision. This step is critically important to the entire process. With the domain in front of you at the Context level (1), you can fill out this picture with domain experts and modify the diagram to best reflect reality. The best way to do this is to send experts the already-created diagram in advance and, after reviewing it, talk about potential changes. This way we can get the full context of the modifications to be made. Inaccuracies in the diagram may arise from our misinterpretation of the materials we received, or shortcomings, and (in the worst case) errors in the existing documentation. Revisions should be carried out until a complete and faithful picture of the reality is obtained.
- Having a picture of the domain at the level of systems, one can go down a level lower, to the level of Containers. We use an analogous tactic - we start by using the available materials. We map personas, systems, containers and the relationships between them.
- As in point 2, we revise the diagrams at level 2 (Container). As a rule, they are much more elaborate than at level 1, so it is worth reserving enough time for this activity.
- After receiving the final shape of the domain at the level of systems and containers, planning to modernize the system or add new functionality to it becomes incomparably easier, and implementation much faster. After all, we have a much more complete picture of the situation and therefore the decisions made become more accurate.
- The road does not end with the creation of C4. At levels 1 and 2, they are an excellent input to Big Picture Event Storming.
How to create C4 quickly?
You can do it manually but you can also use code that is automatically rendered into a finished diagram. The second method is recommended. It’s faster and the learning curve here isn’t very high. The automatic approach is also much easier to maintain through regular updates, and the code that creates the diagram can be committed directly to the project repo.
However, this solution has its drawbacks. For example, sometimes automatically rendered diagrams don’t organize mapped elements in the way we expect them to. Then we need to use the specially-created page relationships (e.g. Rel_L) that force the placement of elements from a given side of the relationship source.
Tools used
- C4-PlantUML - describes in an accessible way how to use Diagram as a Code
- VSCode
- VSCode PlantUML Extension - an extension that allows you to render the written diagrams live
The effect can be seen here.
This is exactly how the work is done during sessions with domain experts. Changes are applied live, and the effects can be seen immediately.
C4 diagrams, in their simplicity, make it possible for people without technical knowledge to instantly understand the output and implement necessary corrections, e.g. on the issue of Persona → System relations. Thus, we have visualized a much broader perspective than that obtained from tech specialists.
What’s next?
Having a completely mapped domain that is a combination of existing documentation and tribal knowledge spread among employees, one can proceed to design functionality or upgrades much more adequately to meet the business needs. What’s more, a better understanding within the team also means higher morale, as we reduce the risk of creating incomplete functionality. We prevent the necessity of frequent revisions and modifications which could arise due to lack of domain knowledge within the team.
Bonus
In addition, if we would like to map the domain more deeply, e.g. focusing on domain events, we can use a Big Picture Event Storming session with the pre-created C4 input. All we need to do in order to process it is pull content from the modeled C4 and convert it to BPES notation.
- Relationships → Events
- Persons → Actors
- Contexts → Systems
- Components → Entry Points
Of course, working on BPES will require additional sessions to get into the details but we already have most of the elements mapped out.
Share this article:
