With Domain Message Flow Modeling — by Dr. Stefan Hofer

In 2020, Nick Tune introduced a useful idea to the Domain-Driven Design (DDD) community: a way to visualize the flow of messages (i.e., commands, events, and queries) in a bounded context architecture. Nick calls his technique Domain Message Flow Modeling and some of the key reasons for using it are:

· Validate newly designed boundaries and interactions by analyzing and uncovering coupling.

· Cheap discovery: Can we identify any hidden complexity before we start implementing?

· Analyzing IT landscapes by focusing on the domain rather than on existing system boundaries.

For a comprehensive introduction to Domain Message Flow Modeling, please see https://github.com/ddd-crew/domain-message-flow-modelling.

Nick says that he was heavily inspired by the C4 Model and by Domain Storytelling. Since Domain Storytelling is a versatile technique, I wondered if it can be adapted for Domain Message Flow Modeling. In software terms, this would probably be called a “backport”. This article summarizes the necessary adaptations. I hope this encourages Domain Storytelling practitioners to try Domain Message Flow Modeling.

A Pictographic Language for Domain Message Flow Modeling

In Domain Storytelling, we distinguish between different symbols: actors, work objects, activities, annotations, groups, and sequence numbers. Actors and work objects are expressed with icons and labeled with their concrete meaning. The concepts of Domain Message Flow Modeling can be mapped to Domain Storytelling’s pictographic language as follows:

*) Which icons you use is up to you. I chose some Google Material icons that resemble Nick Tune’s example.

This is my take on Nick’s “placing an online order” example:

I created this diagram with egon.io, an open-source tool for Domain Storytelling. However, I could have created a similar looking picture with tools like Miro or a whiteboard with sticky notes. The principles of the pictographic language would have been the same (e.g., bounded contexts modeled as actors), just the icons and labels would have looked a bit different.

You might wonder why Domain Message Flow Modeling distinguishes between bounded contexts and systems. Nick’s reasoning — and I am simplifying here — is that a bounded context is something that the organization controls (naming, boundaries, etc.), whereas the “systems” are not in the organization’ s zone of control. Furthermore, I experienced that modeling bounded contexts prevents people from jumping to architectural conclusions (e.g., if “sales”, “notifications”, and “billing” should be implemented as microservices).

In my example, I use annotations to model the message content (e.g., “order id”, “items”, and “payment method”). This resembles the format that Nick describes as “separate message & contents”.

The actual message flow is modeled with activities. In a domain story, an activity is visualized as arrow and usually labeled with a verb. In a “classic” domain story, the first sentence would have read “shopper places order using website”. But from a message flow point of view, the shopper triggers a “place order” command — the shopper’s intention becomes part of the work objects (i.e., event, command, and query). Therefore, the activities in the above example are not labeled; they are reduced to visualizing the flow of messages. The order of the messages is expressed with sequence numbers.

Can you give me an example?

A domain message flow model shows the behavior of bounded contexts — it shows a process, not a structure. That process is illustrated by an example. In Domain Storytelling, we call that scenario-based modeling. “Placing an online order when all items are in stock” is a different scenario from “placing an online order when one item is out of stock”. Each scenario is visualized in a separate picture and might show different bounded contexts and systems.

The goal of scenario-based modeling is not to cover all possible variations but the most important ones — the 80% case, the most common variations, or important error cases.

How the pictures are created

Domain Storytelling combines a pictographic language with a workshop format. How much of the workshop’s collaborative potential can be applied to Domain Message Flow Modeling depends on the situation. Collaborating in workshops makes sense particularly if you want to design to-be architectures (with candidate bounded contexts). Documenting existing architecture (as-is modeling) could also work with less collaboration.


I thank Nick Tune for reviewing a draft of this article.

Learn More

Interested in learning more about Domain Storytelling? Our book is available in print and as e-book. It is part of Addison-Wesley’s new Vaughn Vernon Signature Series. Check out https://domainstorytelling.org/book for buying options.