nwave-ai/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