---
name: eventmodeling-designing-event-models
description: "Designs event-sourced domain models. Maps business processes to immutable events and state projections. Events are the source of truth; state is derived from events for command validation. Use when designing event streaming architectures from domain analysis. Do not use for: brainstorming events from scratch (use eventmodeling-brainstorming-events), optimizing stream sizing or snapshotting (use eventmodeling-optimizing-stream-design), or translating external system events (use eventmodeling-translating-external-events)."
allowed-tools:
  - AskUserQuestion
  - Write
---

# Designing Event Models

## Interview Phase (Optional)

**When to Interview**: Skip if the user has specified: stream identity strategy, command-specific state needs, and read model requirements. Interview when stream boundaries or state design are unclear.

**Interview Strategy**: Establish stream identity and per-command state boundaries before designing. Ambiguous boundaries are the primary cause of the DDD aggregate anti-pattern appearing in event-sourced models.

### Critical Questions

1. **Stream Identity** (Impact: Determines how events are grouped into streams)
   - Question: "What's the entity that owns events? (e.g., orderId, reviewId, customerId) What's the lifetime? Single transaction or years?"
   - Why it matters: Wrong stream identity causes design problems; correct identity keeps streams appropriately scoped
   - Follow-up triggers: If multiple candidates → ask "Which entity's identity would you use to load events for a single command decision?"

2. **Minimal State vs Bundled State** (Impact: Prevents DDD aggregate anti-pattern)
   - Question: "Will different commands need different state? Or does every command need the same full state?"
   - Why it matters: Each command should have minimal, command-specific state—not bundled DDD aggregates
   - Follow-up triggers: If "same full state" → walk through two commands and ask what each actually reads during validation

### Interview Flow

**Conditional Entry**:
```text
If user has provided:
  - Stream identity (which entity ID anchors the stream)
  - AND at least two commands with explicitly different state needs documented
  - AND read model requirements (what queries the UI or processors make)

Then: Skip interview, proceed directly to design

Else: Conduct interview
```

**Phase 1: Stream Boundaries** (Question 1)
- Confirm which entity anchors the stream
- Establish stream lifetime expectations
- Identify whether multiple candidate roots exist and resolve them

**Phase 2: State Design** (Question 2)
- Confirm per-command state isolation
- Identify whether DDD aggregate thinking is present upfront
- Establish minimal state shapes for at least two commands

### Capturing Interview Findings

Append findings to the project's event modeling file:

**File**: `.trogonai/interviews/[project-name]/EVENTMODELING.md`

Use Write tool to add/update this section:

```markdown
## Designing Event Models (eventmodeling-designing-event-models)

### Stream Identity
[From Q1: Which entity? What identity key? Lifetime?]

### Per-Command State Decisions
[From Q2: Which commands need different state? Initial minimal state shapes?]

### Design Decisions
- Stream root: [entity name] identified by [id field]
- State isolation: [confirmed / DDD pattern caught and corrected]
```

Update Interview Trail:
```markdown
| Design | eventmodeling-designing-event-models | Done | Stream identity, per-command state shapes |
```

---

## Core Architectural Rule

 **NEVER use a "DDD Aggregate Root" (bundled state) for command validation** Every command handler has its own minimal state projection. What DDD calls an "aggregate root" is actually a **read model**, not command-validation state.

```text
 WRONG: Using DDD Aggregate as command state
OrderAggregate { orderId, customerId, items[], total, status, paymentId, address, shippedAt, cancelledAt, ... }
    ↑ This is a READ MODEL, not command state
    ↓ NEVER use for command validation
  handleConfirmOrder(OrderAggregate)
  handleShipOrder(OrderAggregate)
  handleCancelOrder(OrderAggregate)

 CORRECT: Minimal state per command
ConfirmOrderState { status, orderId }
    ↓
  handleConfirmOrder(ConfirmOrderState)

ShipOrderState { status, orderId, paymentId }
    ↓
  handleShipOrder(ShipOrderState)

CancelOrderState { status, orderId, createdAt }
    ↓
  handleCancelOrder(CancelOrderState)

OrderSummaryView { orderId, customerId, items[], total, status, paymentId, ... }
    ↑ This is for UI queries, NOT command validation
```

## Purpose
Converts domain analysis into the event sourcing architecture pattern:

**UI/Processor** → **Command** → [Command State Read Model] → **Event** → **Query Read Models** - **UI/Processor**: Entry points that trigger intent
- **Command**: Intent data (can be rejected)
- **Stream Root**: Logical grouping of immutable events (NOT a DDD aggregate bundle)
- **Command State Read Model**: Minimal projection derived from events, optimized for this specific command's validation. Each command gets its own read model interface. Different commands = different shapes. (Categorized as "Command State" for semantic clarity)
- **Event**: Result of successful command (immutable fact: command data + implicit context)
- **Query Read Models**: Rich projections of events optimized for UI/Processor queries. Separate from command state. (Categorized as "Query Models" for semantic clarity)

## Workflow

Given a domain analysis, design a complete event-sourced model:

### 1. Design Event Streams
Events are the immutable source of truth. Each stream holds facts about one entity:
- **Stream Name**: Entity type + identity (Order:order-123)
- **Event Type**: What changed? (past tense: Created, Confirmed, Shipped)
- **Event Data**: Combines command input + implicit stream state facts
- **Causality**: Triggered by which command?

Format:
```text
Stream: Order:order-123

Events (chronological):
1. OrderCreated
   Triggered by: CreateOrder command
   Data: customerId, items[], total, shippingAddress, createdAt
   (from command: customerId, items[], shippingAddress)
   (implicit: total calculated from items)

2. OrderConfirmed
   Triggered by: ConfirmOrder command
   Data: paymentId, confirmedAt
   (from command: paymentId)
   (implicit: orderId from stream, previous status verified)

3. OrderShipped
   Triggered by: ShipOrder command
   Data: shipmentId, shippedAt
   (from command: shipmentId)
   (implicit: orderId, confirmed status verified)
```

**Key Rules**:
- Events are **immutable facts** from successful commands
- Event data = command input + implicit stream state context
- Stream identity is explicit (Order:order-123)
- Event order matters for state reconstruction
- Never modify or delete events
- Events only exist if command succeeded

### 2. Design Command State Read Models (Minimal Per-Command)

 **Critical Rule: Each command must have its own read model (command state). NEVER share read models between commands.** **Naming Convention (for Automation)**:
- `[CommandName]State` = Implemented command state read model
- `[CommandName]StateToDo` = Planned command state read model (marked for implementation)

Examples:
- `PublishReviewState` = implemented
- `EditReviewStateToDo` = planned, needs implementation
- `SellerRespondState` = implemented

**Semantic Categorization**: These are read models, but categorized as "Command State" based on their purpose (command validation, not UI queries).

Command state read models are **derived** from events and **minimal**:
- Read only events needed for a specific command's decision
- Build state by replaying only relevant events
- **ENFORCEMENT**: Different commands = different read model interfaces. Period.
- Each command handler defines what state projection it needs (and ONLY what it needs)
- Projection can be regenerated from events at any time

Example for Order stream with separate command state read model for EACH command:

```text
## ConfirmOrder Command (IMPLEMENTED)
State interface: ConfirmOrderState { status, orderId }
Builder: buildConfirmOrderState(events)
Naming: [CommandName]State = implemented
- OrderCreated event → Set status='Draft'
- OrderConfirmed event → Set status='Confirmed'
(SKIP: items, total, shipping - not needed for this command)

## ShipOrder Command (IMPLEMENTED)
State interface: ShipOrderState { status, orderId, paymentId }
Builder: buildShipOrderState(events)
Naming: [CommandName]State = implemented
(DIFFERENT from ConfirmOrderState)
- OrderCreated event → (skip)
- OrderConfirmed event → Set status='Confirmed', set paymentId
- OrderShipped event → Set status='Shipped'

## CancelOrder Command (PLANNED - NOT IMPLEMENTED)
State interface: CancelOrderStateToDo { status, orderId, createdAt }
Builder: buildCancelOrderStateToDo(events) [STUB - TODO]
Naming: [CommandName]StateToDo = planned, needs implementation
(DIFFERENT from both above)
- OrderCreated event → Set status='Draft', createdAt
- OrderCancelled event → Set status='Cancelled'
```

**Enforcement Rule**:
- ConfirmOrderState used ONLY by handleConfirmOrder
- ShipOrderState used ONLY by handleShipOrder
- NEVER share state between commands
- NEVER create a single "OrderState" for all Order commands

This is **NOT** a full aggregate state bundle—it's minimal, command-specific state access.

### 3. Design Commands
Commands are **intent data from UI or Processor**:
- Represent what user/system wants to do
- Can be rejected (validation failure)
- Only UI or Processor can issue commands
- Load current stream state for validation
- Produce events if valid, or reject if invalid

Format:
```text
Command: ConfirmOrder
Source: UI or Processor (only these can issue)
Input: orderId, paymentId

Processing:
    1. Load current state from Order:orderId stream
    2. Validate preconditions:
       - state.status === 'Draft' (reject: already confirmed)
       - paymentId is valid (reject: invalid payment)
    3. If all valid:
       - Produce: OrderConfirmed event
         - Data: paymentId, confirmedAt
         - Implicit: orderId (from stream), previous status (from state)
    4. If any validation fails:
       - Reject: return error (no event created)

Outcomes:
     Success: OrderConfirmed event appended to stream
     Rejection: Error returned, no event created
```

**Key Rules**:
- Only UI or Processor can issue commands (entry points)
- One command per UI/Processor action
- Commands validate against stream state
- Successful command → Event(s) created
- Failed validation → Command rejected, no event
- Commands are synchronous decision logic (pure)

### 4. Design Read Models
Read models are **projections of events for UI/Processor queries**:
- Built from events (only source is events)
- Optimized for specific query patterns
- Consumed by UI or Processor (for display/decision)
- Can be regenerated from events anytime

Format:
```text
ReadModel: OrderSummaryView
Purpose: UI displays customer order list, Processor checks order status

Subscribed to events:
  - OrderCreated
  - OrderConfirmed
  - OrderShipped
  - OrderCancelled

Data (optimized for queries):
  {
    orderId: string
    customerId: string
    total: number
    status: string
    createdAt: Date
    confirmedAt?: Date
    shippedAt?: Date
  }

Update from events:
  - OrderCreated → Insert row (id, customer, total, status='Draft')
  - OrderConfirmed → Update status='Confirmed', set confirmedAt
  - OrderShipped → Update status='Shipped', set shippedAt
  - OrderCancelled → Update status='Cancelled'

Consumed by:
  - UI: displays list of orders
  - Processor: checks if order can be shipped
```

### 5. Document Event Causality
Show how events relate to each other:

```text
Command Flow:
CreateOrder command
    → OrderCreated event
       ↓ (may trigger external process)
ConfirmOrder command (reads OrderCreated state)
    → OrderConfirmed event
       ↓ (may trigger)
ShipOrder command (reads OrderCreated + OrderConfirmed state)
    → OrderShipped event
```

### 6. Document State Transitions
Show valid state transitions:

```text
Order Stream State Transitions:

Initial state: (empty stream)
  ↓
CreateOrder → OrderCreated
  ↓
State: Draft

Draft state:
  → ConfirmOrder → OrderConfirmed → State: Confirmed
  → CancelOrder → OrderCancelled → State: Cancelled

Confirmed state:
  → ShipOrder → OrderShipped → State: Shipped
  → CancelOrder (rejected - already confirmed)

Shipped state:
  → No more transitions allowed
```

### Output Format

Present complete model as:

```markdown
# Event Model: [Domain]

## Event Streams

### Stream: Order

**Identity**: orderId

**Events**:
- OrderCreated: Initial event creating the order
Data: customerId, items[], total, shippingAddress

- OrderConfirmed: Payment confirmed
Data: paymentId, confirmedAt

- OrderShipped: Order shipped
Data: shipmentId, shippedAt

- OrderCancelled: Order cancelled
Data: cancelledAt, reason

**State Projection (Human Example)**:
For the ConfirmOrder command, we need minimal state:
```text
ConfirmOrderState:
  - orderId: 'order-123'
  - status: 'Draft'
```

For the ShipOrder command, we need different data:
```text
ShipOrderState:
  - orderId: 'order-123'
  - status: 'Confirmed'
  - paymentId: 'payment-456'
```

---

## Commands

### Command: CreateOrder
- Input: customerId, items[], shippingAddress
- Validation: Items valid, customerId exists
- Events produced: OrderCreated
- Possible outcomes: Success (OrderCreated) or Validation error

### Command: ConfirmOrder
- Input: orderId, paymentId
- Validation: Order in Draft status, payment validated
- Events produced: OrderConfirmed
- Possible outcomes: Success or "Already confirmed" error

---

## Read Models (Optional)

### ReadModel: OrderSummaryView
- Purpose: Quick lookup of order status
- Events: OrderCreated, OrderConfirmed, OrderShipped, OrderCancelled
- Queries served: GetOrder(orderId), ListOrdersByCustomer(customerId)

---

## Implementation Notes
- All state is derived from events
- Commands validate against derived state
- No transaction across streams
- Events are source of truth
- Read models can be rebuilt from events
```

## Key Event Sourcing Principles

1. **Events are Facts**: Events describe what happened, not what might happen
2. **Immutable Event Log**: Events are appended, never modified
3. **State is Minimal and Command-Driven**: State is built by replaying events, but ONLY for what a specific command needs to validate. Not all stream fields are needed for all commands.
4. **Not DDD Aggregates**: Stream roots group events logically, but aren't bundles of related data like DDD aggregates. State is determined per-command, not designed upfront for the whole stream.
5. **Commands are Pure**: No side effects, just decision logic against minimal state
6. **Read Models are Separate**: Read models (projections) are separate from command-validation state. Read models can have rich data; command state stays minimal.
7. **Event Causality**: Commands → [minimal state] → Events → [read models]

## Design Patterns

### Compensation Pattern
Handle errors by appending compensation events:
```text
Command: ProcessPayment failed
  → PaymentFailed event
    (triggered by external error)
  → OrderCancelled event (compensation)
    (or retry logic)
```

### Temporal Queries
Answer "what was the state at time T?":
```text
Replay events up to timestamp T
  → Get historical state
```

## Best Practices for Event Model Design

### 1. Design Minimal State Per Command
Each command handler only loads the state it needs:
- "LoadOrderState loads { id, items, total, shipping, customer, payment, status, ... }"
- "ConfirmOrderState loads { status, orderId }"
- "ShipOrderState loads { status, orderId, paymentConfirmed }"

### 2. Separate Command State from Query Models
Keep command-validation state and read models strictly separate:
- **Command State** (minimal): Used by handlers to validate commands
- **Query Models** (rich): Used by UI/Processor to display/query data
- Never share between them

### 3. Name State Interfaces by Command
Use the pattern `[CommandName]State` to make the relationship explicit:
- `PublishReviewState` for PublishReview command
- `EditReviewState` for EditReview command
- `ReviewState` (ambiguous - which command?)

### 4. Document State Transitions Clearly
Show what state changes trigger what commands:
- Include initial state
- Show all valid transitions
- Mark impossible transitions (and why)
- Document rejection conditions

### 5. Make All Constraints Explicit
Transform "obvious" business rules into documented invariants:
- "Obviously can't ship an unconfirmed order"
- "ShipOrder validation: requires status='Confirmed' with paymentId"

### 6. Keep Event Data Factual
Events record facts, not derived values:
- "OrderCreated { items, total }" (total is computed from items)
- "OrderCreated { items[] with unitPrice, shippingAddress }" (total computed in projection)

## Quality Checklist

- [ ] All events are immutable facts (past tense)
- [ ] Events contain only captured data, no computed fields
- [ ] State projection is deterministic from events
- [ ] Each command validates against current state
- [ ] Commands either produce events or reject
- [ ] Event causality is clear
- [ ] State transitions are documented
- [ ] No references between streams in events
- [ ] Read models are optional, not required
- [ ] All logic is state → events (pure functions)