event-modeling（事件建模）

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

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)

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)

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)

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)

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

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

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)

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)

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

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

# Event Model: [Process Name]

## Overview
[What this process accomplishes]

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

## Event Model Diagram

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] | [Fields] | [Command/Automation] | [Read Models] |

## Read Models Detail

| Read Model | Purpose | Updated By Events |
| --- | --- | --- |
| [Name] | [Query it answers] | [Events list] |

## Automations

| Automation | Trigger Event | Action | Produces |
| --- | --- | --- | --- |
| [Name] | [Event] | [What it does] | [Events/Side effects] |

## Patterns and Guidelines

### Given/When/Then Specifications

Each slice can be expressed as:

GIVEN: [Read Model State / Context] WHEN: [Command is executed] THEN: [Events are produced] AND: [Read Models are updated]

Example: GIVEN: Cart exists with items WHEN: PlaceOrder command executed THEN: OrderPlaced event recorded AND: OrderSummaryView updated AND: InventoryReservationRequested event triggered

### Slices (Vertical Features)

A slice includes everything for one feature:

┌─────────────────────────────┐ │ SLICE 1 │ │ ┌─────────────────────┐ │ │ │ Command: PlaceOrder │ │ │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ Event: OrderPlaced │ │ │ └─────────────────────┘ │ │ ┌─────────────────────┐ │ │ │ View: OrderSummary │ │ │ └─────────────────────┘ │ └─────────────────────────────┘

Each slice is independently implementable and testable.

### Blue Print (Implementation Guide)

Event Model becomes implementation blueprint:

1. Commands → API Endpoints / UI Components
2. Events → Event Store Schema
3. Read Models → Database Tables / Views
4. Automations → Event Handlers / Policies

Each slice maps directly to code.

## Workflow

When creating Event Models:

1. **Define Scope**: What process are we modeling?
2. **Brain Dump Events**: List all state changes
3. **Arrange Timeline**: Order events chronologically
4. **Add Commands**: What triggers each event?
5. **Add Read Models**: What data supports each command?
6. **Identify Automations**: What happens automatically?
7. **Validate with Stakeholders**: Does this match reality?
8. **Define Slices**: Group into implementable features

## User-Facing Interface

When invoked directly by the user, this skill creates an Event Model for a business process.

### Execution Workflow

1. **Parse Arguments** - Extract the process name, depth level (overview/standard/detailed), and output format (ascii/mermaid/both). If no process provided, ask the user.
2. **Research Context** - Use MCP servers to understand common patterns for this type of process.
3. **Create Event Model** - Follow the 5-step process: brain dump events, arrange timeline, add commands (blue lane), add read models (green lane), identify automations.
4. **Define Slices** - Group into implementable vertical slices with Given/When/Then specifications.
5. **Generate Output** - Produce visual diagram, commands table, events table, read models table, automations, and implementation slices.

## References

For detailed guidance:

---

**Last Updated:** 2025-12-26