nw-ddd-event-modeling

Event Modeling

Collaborative visual design technique created by Adam Dymitruk. The Event Model IS the specification -- it replaces traditional requirements documents with a single, living visual artifact.

Key Properties

• Collaborative: Everyone participates (devs, business, UX)
• Visual: Colored elements on a timeline (physical or digital board)
• Timeline-based: Events arranged chronologically, left to right
• Spec-generating: Model directly produces testable Given/When/Then specifications
• Technology-agnostic: Describes WHAT happens, not HOW it's implemented

The Color System

Color	Element	Description	Example
Orange	Event	Something that happened (past tense)	OrderPlaced, PaymentReceived
Blue	Command	User intent/action (imperative)	PlaceOrder, ProcessPayment
Green	Read Model/View	Data displayed to user	Order Summary, Shipping Dashboard
White	Screen/UI	User interface wireframe	Order Form, Checkout Page
Yellow	Automation/Policy	System reaction (saga/process manager)	"When PaymentReceived, then ConfirmOrder"
Red	External System	Integration point	Payment Gateway, Email Service

Four Phases

Phase 1: Event Brainstorming (10-20 min)

Discover all meaningful things that happen in the system.

Process: Everyone writes events on orange stickies (past tense, domain language) | Place on timeline (left = earlier, right = later) | No filtering -- capture everything | Group related events vertically (these form swimlanes/slices)

Facilitation tips:

• Start with the happy path -- what happens when everything goes right?
• Then add error/exception events
• Ask: "What happens before this? What happens after?"
• Business people identify events developers miss
• Don't worry about order precision -- rough chronological is fine

Example timeline:

Timeline ─────────────────────────────────────────────────>

[CustomerRegistered] [ItemAddedToCart] [OrderPlaced] [PaymentReceived]
                     [ItemRemovedFromCart]            [PaymentFailed]
                                       [OrderCancelled] [OrderConfirmed]
                                                        [ItemShipped]
                                                        [RefundRequested]

Phase 2: Commands and Views (15-25 min)

Understand what triggers events and what users need to see.

Commands (blue): What action causes each event? Who initiates it? Place ABOVE events.

Read Models (green): What information does the user need to act? What does the screen show after? Place BELOW events.

Screens (white): What does the UI look like? Sketch wireframes. Place at top.

Wiring pattern:

Screen -> Command -> Event(s) -> Read Model -> Screen

Phase 3: Automations and Integrations (10-15 min)

Find system-driven reactions to events.

Automations (yellow): "When [event] happens, the system should [command]." These become sagas or process managers. Place between triggering event and resulting command.

External systems (red): Payment gateways, email services, shipping providers. Integration boundaries.

Phase 4: Given/When/Then Specifications (10-20 min)

Turn the model into precise, testable specifications.

For each command-event combination:

GIVEN:
  - CustomerRegistered { customerId: "C1", name: "Ale" }
  - ItemAddedToCart { cartId: "CART1", itemId: "ITEM1", quantity: 2 }

WHEN:
  - PlaceOrder { cartId: "CART1", customerId: "C1" }

THEN:
  - OrderPlaced { orderId: "O1", customerId: "C1", items: [...], total: 59.98 }

These specifications become: Tests (directly translatable) | Documentation (readable by everyone) | Contract (unambiguous business-dev agreement)

Four Information Flow Patterns

The Event Model reveals four patterns:

1. Command (State Change): Screen -> Command -> Event(s). User action changes state. Implementation: command handler validates, aggregate emits events.

2. View (Information Retrieval): Event(s) -> Projection -> Read Model -> Screen. Events transformed into query-optimized views. Implementation: projection subscribes and updates read model.

3. Automation (System Reaction): Event(s) -> Policy/Saga -> Command. System reacts to events by issuing new commands. Implementation: saga/process manager.

4. Translation (External Integration): External Event -> Translator -> Internal Command (or reverse). Boundary between systems. Implementation: anti-corruption layer.

From Model to Vertical Slices

Each column in the Event Model (Screen -> Command -> Event -> Read Model) becomes a vertical slice -- an independently implementable feature.

           Slice 1         Slice 2         Slice 3
         ┌──────────┐   ┌──────────┐   ┌──────────┐
UI       │ OrderForm │   │ PaymentPg│   │ Dashboard │
         ├──────────┤   ├──────────┤   ├──────────┤
Cmd/Qry  │PlaceOrder │   │ProcessPay│   │GetOrders  │
         ├──────────┤   ├──────────┤   ├──────────┤
Domain   │OrderAgg   │   │PaymentAgg│   │OrderProj  │
         ├──────────┤   ├──────────┤   ├──────────┤
Infra    │EventStore │   │EventStore│   │ReadModelDB│
         └──────────┘   └──────────┘   └──────────┘

Benefits: Each slice independently implementable and deployable | Easy to parallelize across team | Model shows exactly how many slices exist and their dependencies | Each slice maps to a portion of the Event Model

Specification Patterns

Happy path: GIVEN events that set up valid state | WHEN valid command | THEN expected events

Validation failure: GIVEN events (possibly none) | WHEN invalid command | THEN error (no events emitted)

Idempotency: GIVEN events including effect already applied | WHEN same command again | THEN no new events

State-dependent: Same command produces different results depending on prior events

Event Modeling vs Other Techniques

Aspect	Event Modeling	EventStorming	DDD Strategic Design
Focus	Complete system design	Domain exploration	Bounded context mapping
Output	Full spec + implementation slices	Shared understanding	Context map + language
Detail	Very detailed (down to fields)	Medium (event+command level)	High-level (boundaries)
Duration	Half day to full day	Hours to days	Ongoing
Code generation	Directly possible	Not directly	Not directly
Testing	Produces testable specs	Produces insights	Produces guidance

These techniques are complementary: EventStorming to explore/understand | DDD Strategic Design to identify contexts | Event Modeling to design implementation within each context.

Session Facilitation Guide

Preparation: Invite developers + product owner + domain experts + UX designer | Duration: 2-4 hours (new system), 1-2 hours (feature) | Tools: Miro (digital) or large wall with colored stickies | Pre-work: brief domain introduction (2-3 sentences)

Flow: Intro (5 min): explain colors and phases | Event brainstorm (15 min): everyone writes, place on timeline | Organize (10 min): cluster, de-duplicate, identify gaps | Commands & Views (20 min): blue and green stickies | Wire it up (10 min): draw arrows showing data flow | Automations (10 min): policies and external systems | Given/When/Then (20 min): specs for key slices | Review (10 min): walk through entire model as narrative

Common mistakes: Too many events at once (start with happy path) | Technical events instead of business language | Skipping views (read models as important as commands) | Not involving business people | Jumping to implementation before finishing model