Diagram Types

EventFlow auto-generates visualizations from your .flow files. Three diagram types serve different audiences and purposes.

Overview

Diagram	Audience	Shows	Best For
Lane Diagram	PM, Design, QA	Event flow between actors	Event Storming, Collaborative sessions
State Diagram	Developers	State transitions	Technical documentation
Combined Diagram	Full team	Both events and states	Complete system overview

Generating Diagrams

# Generate Lane diagram (default for multi-actor)
eventflow diagram order.flow --type=lane

# Generate State diagram (default for single machine)
eventflow diagram order.flow --type=state

# Generate Combined diagram
eventflow diagram order.flow --type=combined

# Output formats
eventflow diagram order.flow --format=html  # Interactive
eventflow diagram order.flow --format=svg   # Static
eventflow diagram order.flow --format=png   # Image

Choosing the Right Diagram

• Non-technical stakeholders → Lane Diagram
• Technical documentation → State Diagram
• Complete system review → Combined Diagram

Lane Diagram

"Who communicates with whom?"

Best for non-developers. Shows actor-to-actor communication via events.

Example

From this EventFlow:

scenario: order process

  on> :checkout from @customer
    validate stock
    emit :payment_request to @payment

  on :payment_success from @payment
    send confirmation to @customer

Generates:

┌─────────────┬─────────────┬──────────────┐
│  @customer  │   @system   │   @payment   │
├─────────────┼─────────────┼──────────────┤
│             │             │              │
│ :checkout   │             │              │
│ ════════════╪══>          │              │
│             │ validates   │              │
│             │             │              │
│             │ :payment_   │              │
│             │ request     │              │
│             │ ════════════╪══>           │
│             │             │              │
│             │             │ :payment_    │
│             │             │ success      │
│             │ <═══════════╪══════════════│
│             │             │              │
│             │ confirmation│              │
│ <═══════════╪═════════════│              │
│             │             │              │
└─────────────┴─────────────┴──────────────┘

═══> = Event flow between actors

Lane Rules

1. Automatic inference - lanes created from @actor usage
2. Order - lanes appear in order of first usage
3. Arrows = Events - all arrows represent event communication

State Diagram

"How does the machine transition between states?"

Best for developers. Shows state machine logic.

Example

                        @order

    ┌─────────────────────────────────────────────┐
    │                                             │
    │  ┌─────────┐    :checkout    ┌────────────────────┐
    │  │  #cart  │ ───────────────>│ #awaiting_payment  │
    │  └─────────┘                 └────────────────────┘
    │                                      │
    │                          ┌───────────┴───────────┐
    │                          │                       │
    │                  :payment_success         :payment_failed
    │                          │                       │
    │                          ▼                       ▼
    │                   ┌──────────┐          ┌────────────────┐
    │                   │  #paid   │          │ #payment_failed│
    │                   └──────────┘          └────────────────┘
    │                          │
    │                   :stock_reserved
    │                          │
    │                          ▼
    │                  ┌────────────┐
    │                  │ #fulfilled │
    │                  └────────────┘
    │                                             │
    └─────────────────────────────────────────────┘

    Legend: ─── = transition, ▼ = direction

State Diagram Features

• Shows all states in the machine
• Shows transition triggers (events)
• Shows branching paths
• Highlights initial and final states

Combined Diagram

"Full picture: who talks to whom, and what state changes occur?"

Best for complete system documentation.

Example

┌─────────────┬──────────────────────────┬──────────────┐
│  @customer  │         @order           │   @payment   │
├─────────────┼──────────────────────────┼──────────────┤
│             │                          │              │
│             │  ○ #cart                 │              │
│             │                          │              │
│ :checkout   │                          │              │
│ ════════════╪══>                       │              │
│             │      │                   │              │
│             │      ▼                   │              │
│             │  ● #awaiting_payment     │              │
│             │                          │              │
│             │  :payment_request        │              │
│             │  ════════════════════════╪══>           │
│             │                          │              │
│             │                          │ processes    │
│             │                          │              │
│             │               :payment_success          │
│             │  <═══════════════════════╪══════════════│
│             │      │                   │              │
│             │      ▼                   │              │
│             │  ● #paid                 │              │
│             │                          │              │
│ :confirmed  │                          │              │
│ <═══════════╪══════════════════════════│              │
│             │      │                   │              │
│             │      ▼                   │              │
│             │  ● #fulfilled            │              │
│             │                          │              │
└─────────────┴──────────────────────────┴──────────────┘

Legend: ○ = initial state, ● = current state, ═══> = event

Combined Diagram Features

• Shows both event flow AND state changes
• Events as horizontal arrows
• States as vertical progression
• Clear machine boundaries

Interactive HTML Features

When generating HTML format:

• Zoomable diagram - pan and zoom for large systems
• Clickable elements - click states and events for details
• Scenario walkthrough - step-by-step animation
• Source highlighting - click diagram → highlight code
• Toggle views - switch between diagram types
• Event flow animation - visualize event propagation

eventflow diagram system.flow --format=html --serve
# Opens interactive diagram in browser

System Diagrams

For multi-machine systems, diagrams show all machines:

eventflow diagram system.flow --type=lane

┌─────────────┬─────────────┬─────────────┬─────────────┐
│  @customer  │   @order    │  @payment   │ @inventory  │
├─────────────┼─────────────┼─────────────┼─────────────┤
│ :checkout   │             │             │             │
│ ════════════╪══>          │             │             │
│             │             │             │             │
│             │ :pay_request│             │             │
│             │ ════════════╪══>          │             │
│             │             │             │             │
│             │ :pay_success│             │             │
│             │ <═══════════╪═════════════│             │
│             │             │             │             │
│             │ :reserve    │             │             │
│             │ ════════════╪═════════════╪══>          │
│             │             │             │             │
│             │ :reserved   │             │             │
│             │ <═══════════╪═════════════╪═════════════│
│             │             │             │             │
│ :confirmed  │             │             │             │
│ <═══════════╪═════════════│             │             │
└─────────────┴─────────────┴─────────────┴─────────────┘