event-modeling

name	event-modeling
description	Designs systems using Event Modeling.

icon: 📊

Event Modeling

A set of vertical slices that fully describe a system's behavior. Each slice is independently implementable and testable. The model uses business language throughout — no infrastructure or technical terms.

Slice Types

Three types. Every behavior in the system fits one:

STATE_CHANGE — user does something

• Screen → Command → Event
• Command produces one or more events
• May have error events for failure paths

STATE_VIEW — system shows something

• Events → Read Model → Screen
• Read model aggregates data from one or more events

AUTOMATION — system reacts to something

• Event → Processor → Command → Event
• Background process, no user interaction

See references/slice-types.md for element rules, dependency patterns, and naming conventions.

Design Process

1. Understand the domain — Identify aggregates (core business entities), actors, and high-level use cases. Ask about business processes, not technical implementation.
2. High-level model — Draft all slices without field details. Show the flow between them — which events feed which read models, which screens lead to which commands. Format as markdown with one section per slice.
3. Slice detail — Walk through one slice at a time. Define fields with types and example values. Identify business rules (real domain rules, not simple validations). Write specifications as Given/When/Then scenarios.

Existing codebases: Read the code to extract domain concepts. Map operations to slice types (writes → STATE_CHANGE, reads → STATE_VIEW, background → AUTOMATION). Extract specs from unit tests and comments.

Output Format

Produce markdown. Design for human readability.

Write model artifacts to files. Ask the user where they want them. Update the files as the model evolves.

High-level model:

# [System Name] Event Model

## Aggregates
- Owner — pet owners who use the clinic
- Pet — animals registered to owners

## Slices

### Register Owner [STATE_CHANGE]
Aggregate: Owner
Screen: Owner Registration Form
Command: Register Owner → Event: Owner Registered
Error: → Owner Registration Failed

### View Owner Profile [STATE_VIEW]
Aggregate: Owner
Events: Owner Registered, Pet Registered → Read Model: Owner Profile
Screen: Owner Profile

### Notify Vet of New Patient [AUTOMATION]
Trigger: Pet Registered → Processor: New Patient Notifier
Command: Send Notification → Event: Vet Notified

Detailed slice:

## Register Owner [STATE_CHANGE]
Aggregate: Owner

### Command: Register Owner
  firstName: String — "George"
  lastName: String — "Franklin"
  address: String — "110 W. Liberty St."
  city: String — "Madison"
  telephone: String — "6085551023"

### Event: Owner Registered
  ownerId: UUID — <generated>
  firstName: String — "George"
  lastName: String — "Franklin"
  address: String — "110 W. Liberty St."
  city: String — "Madison"
  telephone: String — "6085551023"

### Event: Owner Registration Failed
  errors: Map — {"lastName": "required"}

### Specifications

#### Successfully register with valid data
Given: (no prior state)
When: Register Owner
  firstName: George, lastName: Franklin
  address: 110 W. Liberty St., city: Madison
  telephone: [phone]
Then: Owner Registered
  ownerId: <generated>, firstName: George, lastName: Franklin

#### Fail when required fields missing
Given: (no prior state)
When: Register Owner
  firstName: George, city: Madison
Then: Owner Registration Failed
  errors: {address: required, telephone: required}

#### Business rules
- All fields mandatory: firstName, lastName, address, city, telephone
- Telephone must be numeric, max 10 digits

Adapt the format to the domain — what matters is that a person can scan it and quickly validate correctness.

Anti-Patterns

• Technical language in element names ("insertOwnerRecord" → "Register Owner")
• Skipping STATE_VIEW slices — every query/display is a slice
• Circular dependencies between elements
• Specs that test simple validation instead of business rules
• Combining multiple commands in one slice — one command per STATE_CHANGE