The journeylism of @yreynhout

On CQRS, DDD(D), ES, …

Message interaction diagrams

The other day, while commenting on my EventBuilders post, Thorsten Krüger questioned how one would keep an overview of all the messages (commands, events) floating around the system in a meaningful way.

Anybody who has built larger messaging systems (or parts thereof), or used messaging to integrate with other systems, will acknowledge that some form of contract/protocol negotiation has taken place, such that all parties can communicate with one another. At times, on the surface of it, it might look like nothing more than a form of data-exchange. But if you question why that data goes to and fro, usually there’ll be some greater goal, a business function that data supports. Other times it might really be behavior going over the wire, in the form of serialized messages that want your end or their end to mutate state and reply or publish upon completion (success/failure).

Nevertheless, as the title of this post suggests, visual documentation is what will keep the bigger picture clear. At a high level, visual documentation of communication between bounded contexts will function somewhat like a context map, but it’s more focused on the command/event interactions supporting a specific use case/user story/business function. Mind you that this way of documenting your system’s interactions is not limited to communication between bounded contexts. It could as well be breaking down a process that affects multiple aggregates, tied together by a saga or several eventhandlers triggering one command after another.
The most useful tool I’ve found to document the flow of messages is by far interaction diagrams, and more specifically sequence diagrams. Below you’ll find an example using the excellent (seriously, try it and if you like it, consider buying it).
Communication between and in bounded contexts


2 responses to “Message interaction diagrams

  1. Eti July 31, 2011 at 08:12

    Hi, thanks for the article, i was wandering what is a good way to represent the message flow in an application. With the sequence diagrams expressing sending commands is easy but publishing messages to subscribers is a bit tricky. Using some kind of dotted arrow or other kind of visual difference from sending commands helps but the fact that is a published message is still not very expressive. Do you have any suggestions on how to represent in a diagram the concept of publishing a message to a bunch of subscribers?

    PS: you should add google auth to comments

  2. yreynhout July 31, 2011 at 11:28

    I think you’ve missed the point somewhat. The sequence diagram should represent one “business operation”. That might involve several commands and events – differentiated by using the present and past tense in the diagram above – being sent/published to various bounded contexts. I’d suspect you’d have one of these for all non-trivial business operations (e.g. anything that deviates from the “one command produces one event” pattern), often showing alternate flows involving loops and conditions. By identifying subscribers and showing them as receivers of an event in the diagram, I hardly see any need to differentiate between messaging interaction semantics (i.e. “send”, “publish”, …). That’s what the past and present tense are for, along with the mantra “commands are sent, events are published”.
    If on the other hand, you want to present a general overview of all messages being sent/published between or within the various bounded contexts, regardless of the business operation they relate to, a visual indication to differentiate commands and events might make it more comprehensible.
    Of course, you should take this advice with a grain of salt. Nothing wrong with making a picture clearer.

    PS: There doesn’t seem to be an option over here at to do so (requires a plugin if I’m not mistaken).

Leave a Reply

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

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

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

%d bloggers like this: