/nw-ddd-event-modeling

name: nw-ddd-event-modeling
description: Event Modeling facilitation technique — brainstorm events, identify commands and views, define aggregate boundaries, write Given-When-Then specifications
user-invocable: false
disable-model-invocation: true

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