Diagram Types

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

Overview

Diagram	Audience	Shows	When Created	Best For
Lane Diagram	PM, Design, QA	Event flow between actors	Sessions 1-2 (First)	Event Storming, Collaborative sessions
State Diagram	Developers	State transitions	Session 4 (After derivation)	Technical documentation
Combined Diagram	Full team	Both events and states	Session 5 (Review)	Complete system overview

Diagram Creation Order

EventFlow follows a lane-first approach to diagram creation:

1. Sessions 1-2: Create Lane Diagrams (events and actors) with the full team
2. Session 4: Derive states from lane diagram wait points (developer only)
3. Session 4+: Generate State Diagrams from derived states
4. Session 5: Review Combined Diagrams with the full team

This order ensures:

• Non-technical stakeholders participate in early sessions without state confusion
• States are systematically derived from wait points, not invented arbitrarily
• Technical complexity is introduced only when the event flow is complete

States are defined explicitly in event handlers using the moves to #state syntax.

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 (api)
    validate stock
    emit :payment_request to @payment

  on :payment_success from @payment
    send confirmation to @customer

Generates:

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

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

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