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