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:

• Invoke docs-management skill for Event Modeling patterns

• Verify methodology via MCP servers (perplexity, eventmodeling.org)

• 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:

- Define Scope: What process are we modeling?

- Brain Dump Events: List all state changes

- Arrange Timeline: Order events chronologically

- Add Commands: What triggers each event?

- Add Read Models: What data supports each command?

- Identify Automations: What happens automatically?

- Validate with Stakeholders: Does this match reality?

- 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

- Parse Arguments - Extract the process name, depth level (overview/standard/detailed), and output format (ascii/mermaid/both). If no process provided, ask the user.

- Research Context - Use MCP servers to understand common patterns for this type of process.

- Create Event Model - Follow the 5-step process: brain dump events, arrange timeline, add commands (blue lane), add read models (green lane), identify automations.

- Define Slices - Group into implementable vertical slices with Given/When/Then specifications.

- 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