event-modeling

What this skill does

# Event Modeling Skill

## When to Use This Skill

Use this skill when:

- **Event Modeling tasks** - Working on adam dymitruk's event modeling methodology with swimlanes
- **Planning or design** - Need guidance on Event Modeling approaches
- **Best practices** - Want to follow established patterns and standards

## Overview

Create Event Models using Adam Dymitruk's visual methodology for designing event-driven systems.

## MANDATORY: Documentation-First Approach

Before creating Event Models:

1. **Invoke `docs-management` skill** for Event Modeling patterns
2. **Verify methodology** via MCP servers (perplexity, eventmodeling.org)
3. **Base guidance on Adam Dymitruk's original methodology**

## Event Modeling Fundamentals

```text
Event Modeling Structure:

TIME FLOWS LEFT TO RIGHT ───────────────────────────────────────────►

┌─────────────────────────────────────────────────────────────────────┐
│ BLUE: UI / Commands / External Triggers                            │
│ ┌──────────┐  ┌──────────┐  ┌──────────┐                           │
│ │ Screen/  │  │ Button   │  │ API      │                           │
│ │ Wireframe│  │ Click    │  │ Call     │                           │
│ └────┬─────┘  └────┬─────┘  └────┬─────┘                           │
├──────┼─────────────┼─────────────┼──────────────────────────────────┤
│      ▼             ▼             ▼                                  │
│ ORANGE: Domain Events (State Changes)                              │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                 │
│ │ OrderPlaced  │ │ OrderPaid    │ │ OrderShipped │                 │
│ └──────────────┘ └──────────────┘ └──────────────┘                 │
│      │                 │               │                            │
├──────┼─────────────────┼───────────────┼────────────────────────────┤
│      ▼                 ▼               ▼                            │
│ GREEN: Read Models / Projections                                   │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                 │
│ │ Order List   │ │ Payment      │ │ Shipping     │                 │
│ │ View         │ │ Status       │ │ Dashboard    │                 │
│ └──────────────┘ └──────────────┘ └──────────────┘                 │
└─────────────────────────────────────────────────────────────────────┘
```

## Four Types of Specifications

### 1. Commands (Blue Lane - Top)

```text
Commands: User intentions that may cause state changes

CHARACTERISTICS:
- Represent user actions or external triggers
- May succeed or fail (validation)
- Produce one or more events on success
- Include wireframes/mockups for UI commands

EXAMPLES:
┌─────────────────────────────┐
│ PlaceOrder                  │
├─────────────────────────────┤
│ • Customer ID               │
│ • Items: [ProductId, Qty]   │
│ • Shipping Address          │
│ • Payment Method            │
└─────────────────────────────┘
```

### 2. Events (Orange Lane - Middle)

```text
Events: Facts that have happened (past tense, immutable)

CHARACTERISTICS:
- Past tense naming (OrderPlaced, not PlaceOrder)
- Immutable once recorded
- Capture what happened and when
- Single source of truth

NAMING CONVENTION:
✓ OrderPlaced
✓ PaymentReceived
✓ ShipmentDispatched
✗ PlaceOrder (command, not event)
✗ OrderUpdate (too vague)

EXAMPLE:
┌─────────────────────────────┐
│ OrderPlaced                 │
├─────────────────────────────┤
│ • OrderId: guid             │
│ • CustomerId: guid          │
│ • Items: [...]              │
│ • PlacedAt: timestamp       │
│ • TotalAmount: decimal      │
└─────────────────────────────┘
```

### 3. Read Models (Green Lane - Bottom)

```text
Read Models: Projections optimized for queries

CHARACTERISTICS:
- Built from events
- Optimized for specific query patterns
- Can be rebuilt from event stream
- Eventually consistent

TYPES:
- List views (showing multiple items)
- Detail views (single item details)
- Dashboards (aggregations)
- Search indexes

EXAMPLE:
┌─────────────────────────────┐
│ OrderSummaryView            │
├─────────────────────────────┤
│ • OrderId                   │
│ • CustomerName              │
│ • Status (derived)          │
│ • ItemCount                 │
│ • TotalAmount               │
│ • LastUpdated               │
└─────────────────────────────┘
```

### 4. Automations (Policies/Reactions)

```text
Automations: Processes triggered by events

CHARACTERISTICS:
- React to events automatically
- May produce commands or integrate external systems
- Represent business policies
- Handle async processing

NOTATION:
┌─────────────────────────────┐
│ ⚡ PaymentReceivedPolicy    │
├─────────────────────────────┤
│ WHEN: PaymentReceived       │
│ THEN: InitiateShipment      │
└─────────────────────────────┘
```

## Event Modeling Process

### Step 1: Brain Dump Events

```text
Brainstorm all domain events (orange stickies):

1. Gather stakeholders
2. Ask: "What happens in this process?"
3. Write events in past tense
4. Don't worry about order yet
5. Include all significant state changes

Example Output:
- OrderPlaced
- OrderConfirmed
- PaymentReceived
- PaymentFailed
- InventoryReserved
- ShipmentCreated
- ShipmentDispatched
- OrderDelivered
```

### Step 2: Arrange Timeline

```text
Organize events chronologically:

1. Find the "happy path" events
2. Arrange left to right
3. Group related events vertically
4. Identify parallel flows
5. Note temporal dependencies

Timeline:
OrderPlaced → OrderConfirmed → PaymentReceived → InventoryReserved → ShipmentCreated → ShipmentDispatched → OrderDelivered
                                   │
                                   └→ PaymentFailed → OrderCancelled
```

### Step 3: Add Commands (Blue)

```text
What triggers each event?

For each event, ask:
- What user action caused this?
- What external system triggered it?
- Is there a UI screen involved?

Add commands above events they produce:
[PlaceOrder] → OrderPlaced
[ProcessPayment] → PaymentReceived
[DispatchShipment] → ShipmentDispatched
```

### Step 4: Add Read Models (Green)

```text
What information is needed for each command?

For each command, ask:
- What data does the user need to see?
- What validation data is required?
- What views enable this action?

Add read models below events that populate them:
OrderPlaced → [OrderConfirmationView]
ShipmentDispatched → [TrackingDashboard]
```

### Step 5: Identify Automations

```text
What happens automatically?

Look for:
- Events that trigger other events
- Integration with external systems
- Time-based rules
- Business policies

Example:
PaymentReceived → ⚡ ReserveInventoryPolicy → InventoryReserved
```

## Event Model Template

```markdown
# Event Model: [Process Name]

## Overview
[What this process accomplishes]

## Actors
- [User type 1]
- [User type 2]
- [External system]

## Event Model Diagram

```text
TIME ──────────────────────────────────────────────────────────────►

COMMANDS (Blue)
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ Cmd 1   │    │ Cmd 2   │    │ Cmd 3   │    │ Cmd 4   │
└────┬────┘    └────┬────┘    └────┬────┘    └────┬────┘
     │              │              │              │
     ▼              ▼              ▼              ▼
EVENTS (Orange)
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ Event1  │───►│ Event2  │───►│ Event3  │───►│ Event4  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
     │              │              │              │
     ▼              ▼              ▼              ▼
READ MODELS (Green)
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ View 1  │    │ View 2  │    │ View 3  │    │ View 4  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
```

## Commands Detail

| Command | Input | Produces Events | Read Model Needed |
|---------|-------|-----------------|-------------------|
| [Name] | [Data] | [Events] | [View] |

## Events Detail

| Event | Data | Triggered By | Updates |
|-------|------|--------------|---------|
| [Name] | [F