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

```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]	[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