Effective communication using architectural diagrams

I’m a strong proponent of DDD principles and overall everything that creates an ubiquitous language and a common understanding.

In my experience I struggled to create such common ground using diagramming techniques like UML and through different and improvised approaches, I always needed to create something similar to C4, which I now use with a slight, but to me, fundamental change.

Using C4 following the proposed layering structure, part of my stakeholders struggle to understand the jump between context and container diagrams.

While presenting the solution architecture, going from context to container diagrams, domain experts that do not necessarily have technical background or are simply not interested in technicalities struggle to follow the conversation and as a result, are not able to effectively provide feedback.

This is a fundamental issue as it creates a communication breakdown socialising functional requirements and so a suboptimal definition of non-functional ones.

The change I found to be effective is to depict the four layers as:

• first layer, the context of the whole system — as proposed by C4
• second layer, the functional bounded context components of the system
• third layer, hosts the container definition — as proposed by C4
• fourth layer, the components — as proposed by C4

effectively shifting the representation of one level.

As an example, if I’m designing a marketplace solution I would propose the following diagrams:

System Context Diagram

Functional Bounded Context Diagram

Order System Container Diagram

Each system will be described using both container and component diagrams providing details for teams responsible for the delivery.

The benefits I noticed following the proposed approach are:

• Non technical domain experts and technical people are able to share a wider conversational ground, improving the overall quality of delivery
• The improved information flow allows for critical thinking resulting in innovative solutions
• All four levels are now easily maintainable. I tend, and I see a growing number of people that reports the same, to avoid using layer four, code, of the C4 proposed approach as it is difficult to maintain
• The whole representation is now coherent as there is no need to bring into the mix a different diagramming technique
• Improved readability and maintainability of the solution architecture as the Functional Bounded Context provides a view of the interactions across different systems