Domain Message Flow Template

One scenario as numbered commands, events and queries between contexts: notation, sequence diagram, message register, checks, failure paths

ArchitekturStandardDDD Crew Domain Message Flow Modellingdomain message flow diagramAktualisiert 29.10.2026

Im Editor öffnen.md herunterladen

Anleitung: Use it to test a candidate set of bounded contexts against one business scenario before writing contracts. Fill the participants and the numbered message register first, then the design checks. The main pitfall is a flow of more than about nine messages, which usually hides a misplaced boundary.

Vorschau

Domain Message Flow: [Scenario name]

Model of one business scenario as a numbered sequence of commands, events and queries passing between actors, bounded contexts and external systems. It tests whether a proposed set of bounded contexts can carry the scenario with clear ownership and few, well-named messages, before anyone writes an API or event contract. Structure informed by the Domain Message Flow Modelling technique of the DDD Crew. Replace every [bracketed] value and every row marked Example. Worked examples use the invented online grocery retailer from the Context Map template (architecture/context-map).

Field	Value
Scenario ID	[MF-ORDER-01]
Scenario	[Shopper places an order with a delivery slot]
Trigger	[Shopper selects "Place order"]
Outcome	[Order accepted, slot reserved, payment authorised, picking planned]
Contexts involved	[Basket and Checkout, Catalogue, Slot Booking, Payments, Fulfilment]
Version	[0.1]
Status	[Draft / Agreed / Implemented / Superseded]
Owner	[@domain-architect]
Participants	[@team-leads], [@product-owner]
Last updated	YYYY-MM-DD
Related documents	Context Map (`architecture/context-map`), Bounded Context Canvases (`architecture/bounded-context-canvas`), Event API Specification (`architecture/event-api-specification`)

1. Scenario description

[Scenario narrative. Example: A signed-in shopper with a full basket chooses a one-hour delivery slot and places the order. Prices are fixed at the moment of ordering. The slot must be reserved, the payment authorised (not yet captured) and the order handed to Fulfilment so picking can be planned. If payment is declined the slot is released and the shopper returns to checkout.]

Assumptions for this flow

Example: The shopper is already signed in; authentication is out of scope.
Example: The slot was offered on the basket page a few minutes earlier and may have filled up since.
[Assumption]

2. Participants

ID	Participant	Type	Owning team	Notes
P-01	Example: Shopper	Human actor	n/a	Uses web or mobile app
P-02	Example: Basket and Checkout	Bounded context	Team Checkout	Coordinates the scenario
P-03	Example: Catalogue	Bounded context	Team Range	Owns current prices
P-04	Example: Slot Booking	Bounded context	Team Slots	Owns slot capacity
P-05	Example: Payments	Bounded context	Team Payments	Wraps the payment provider
P-06	Example: Payment provider	External system	Vendor	Card authorisation
P-07	Example: Fulfilment	Bounded context	Team Fulfilment	Plans picking
[P-NN]	[Name]	[Human actor / Bounded context / External system]	[Team]	[Notes]

3. Message notation

Type	Naming style	Meaning	Expected reply
Command	Imperative verb: `PlaceOrder`	Asks the receiver to do something; it may refuse	Accepted, rejected, or a later event
Event	Past tense: `OrderPlaced`	States a fact that has happened in the sender's context	None; receivers decide what to do
Query	Question form: `GetCurrentPrices`	Asks for information without changing state	The answer, treated as part of the same message

For time-driven messages, say exactly which of these you mean: "within" a period (a deadline), "after" a period (a delay) or "every" period (a schedule). They lead to very different designs.

4. Message flow diagram

Happy path of the scenario. Solid arrows are commands and queries, dashed arrows are events and query replies.

5. Message register

No.	Type	Message	From	To	Significant data	Schema owner
1	Command	Example: `PlaceOrder`	Shopper	Basket and Checkout	basketId, slotId, paymentMethodToken	Basket and Checkout
2	Query	Example: `GetCurrentPrices` (reply: prices)	Basket and Checkout	Catalogue	productIds; reply: unit price per product, price valid-until time	Catalogue
3	Command	Example: `ReserveSlot`	Basket and Checkout	Slot Booking	slotId, orderId, reservation period 15 minutes	Slot Booking
4	Event	Example: `SlotReserved`	Slot Booking	Basket and Checkout	slotId, orderId, reservationExpiresAt	Slot Booking
5	Command	Example: `AuthorisePayment`	Basket and Checkout	Payments	orderId, amount, currency, paymentMethodToken	Payments
6	Command	Example: `CreateAuthorisation`	Payments	Payment provider	provider-specific request, built by the anticorruption layer	Payment provider
7	Event	Example: `PaymentAuthorised`	Payments	Basket and Checkout	orderId, authorisationId, amount	Payments
8	Event	Example: `OrderPlaced`	Basket and Checkout	Fulfilment	orderId, lines (productId, quantity, unit price), slotId, substitution preferences (added in v4, see MFF-02)	Basket and Checkout
9	Event	Example: `PickingPlanned`	Fulfilment	Shopper (via notification)	orderId, planned picking window	Fulfilment
[N]	[Type]	[Message]	[Sender]	[Receiver]	[Fields]	[Context]

Worked amount (Example): the basket holds 2 x 4.20, 1 x 12.50 and 3 x 3.15, so the goods total 8.40 + 12.50 + 9.45 = 30.35. With a delivery fee of 4.99, message 5 carries amount 35.34 in the shop currency.

6. Design checks

Check	Question	Result	Note
DC-01	Does every message have exactly one owning context for its schema?	[Yes / No]	Example: Yes
DC-02	Does any context ask another for data it needs on every request (chatty queries)?	[Yes / No]	Example: Message 2 runs on every order; consider a price snapshot in the basket
DC-03	Are commands sent only to the context that owns the decision?	[Yes / No]	Example: Yes
DC-04	Does any context need to know the internal model of another (leaking language)?	[Yes / No]	Example: Message 6 hides the provider model behind Payments
DC-05	Can the scenario finish if one receiver is slow or down?	[Yes / No / Partly]	Example: Partly: Fulfilment can consume `OrderPlaced` later, payment cannot be skipped
DC-06	Is the number of messages within about 5 to 9?	[Yes / No]	Example: Yes, 9
DC-07	Are time-driven rules stated as within, after or every?	[Yes / No]	Example: Slot reservation expires 15 minutes after message 4
[DC-NN]	[Question]	[Result]	[Note]

7. Alternative and failure paths

Path	Diverges at	Messages	End state
ALT-01 Example: Payment declined	7	7a Event `PaymentDeclined` (Payments to Basket and Checkout), 7b Command `ReleaseSlot` (Basket and Checkout to Slot Booking), 7c Event `SlotReleased` (Slot Booking to Basket and Checkout)	Shopper back at checkout, no order created
ALT-02 Example: Slot filled since it was offered	4	4a Event `SlotUnavailable` (Slot Booking to Basket and Checkout)	Shopper asked to choose another slot; payment not attempted
ALT-03 Example: Price changed since basket was built	2	No new message; Basket and Checkout shows the new total and asks the shopper to confirm	Order waits for confirmation
[ALT-NN]	[Step]	[Messages]	[End state]

8. Findings and boundary changes

ID	Finding	Change	Record
MFF-01	Example: Basket and Checkout orchestrates four contexts in one request	Accept for now; review if a fifth context joins the flow	ADR-042
MFF-02	Example: Fulfilment needs substitution preferences that are not in `OrderPlaced` v3	Add field in `OrderPlaced` v4, owned by Team Checkout	Context Map REL-03
[MFF-NN]	[Finding]	[Change]	[Link]

References

DDD Crew, Domain Message Flow Modelling, https://github.com/ddd-crew/domain-message-flow-modelling (technique, variants and modelling tips; checked 2026-10-30).
Related templates: Context Map (architecture/context-map), Core Domain Chart (architecture/core-domain-chart), EventStorming Summary (architecture/event-storming-summary), Ubiquitous Language (architecture/ubiquitous-language), Event API Specification (architecture/event-api-specification), Event Sourcing and CQRS (architecture/event-sourcing-cqrs).

Standard and licence note

Structure informed by the Domain Message Flow Modelling technique published by the DDD Crew (Kacper Gunia, Zsofia Herendi, Nick Tune and contributors, https://github.com/ddd-crew/domain-message-flow-modelling). As checked on 2026-10-30, the repository README states CC BY 4.0 while its licence file states CC BY-SA 4.0. This template does not copy the technique's text or images; the notation table, checks, examples and guidance are original to this collection and the technique is cited by name only. Commands, events and queries are general terms of message-based design. Template licence: MIT.