Lane Diagrams

Lane diagrams show event communication between actors. They're ideal for collaborative sessions and non-technical stakeholders.

What Lane Diagrams Show

• Actors as vertical lanes
• Events as arrows between lanes
• Actions as text within lanes
• Time flowing top to bottom

Basic Example

From this EventFlow:

machine: @order

scenario: checkout process

  on :checkout from @customer (api)
    validate cart
    emit :payment_request to @payment

  on :payment_success from @payment
    order moves to #paid
    emit :confirmation to @customer

Generates:

Lane Inference

Lanes are automatically created from @actor references in your code:

on :checkout from @customer (api)        // Creates @customer lane
  emit :payment_request to @payment // Creates @payment lane
  emit :notify to @admin            // Creates @admin lane

Lane order is determined by first appearance.

Reading Lane Diagrams

Arrows

────────>   Event sent (request)
<────────   Event received (response)

Time

Time flows top to bottom. Events higher up happen before events below.

Actions

Text within a lane represents actions that machine performs:

│   @order    │
│             │
│ validate    │  ← Action
│ cart        │
│             │
│ calculate   │  ← Action
│ total       │

Multi-Machine Systems

Lane diagrams excel at showing multi-machine interactions:

system: e-commerce

machine: @order
  on :checkout from @customer (api)
    emit :check_inventory to @inventory
    emit :process_payment to @payment

machine: @inventory
  on :check_inventory from @order
    ? stock available
      emit :inventory_ok to @order

machine: @payment
  on :process_payment from @order
    ? payment successful
      emit :payment_ok to @order

Generates:

Parallel Events

When multiple events are emitted simultaneously:

on :checkout from @customer (api)
  emit :check_payment to @payment       // Parallel
  emit :check_fraud to @fraud           // Parallel
  emit :check_inventory to @inventory   // Parallel

Shown at the same vertical level:

Conditional Flows

Guards and conditions can be shown:

on :payment_result from @payment
  ? payment successful
    emit :ship_order to @warehouse
  otherwise
    emit :payment_failed to @customer

Lane Diagrams as Input for State Derivation

Lane diagrams are the foundation for state machine design in EventFlow. They show the event flow between actors, and serve as the input for deriving states.

The Lane-First Approach

1. Draw the lane diagram — show WHO sends WHAT to WHOM
2. Identify wait points — where does the system pause for external input?
3. Derive states — each wait point becomes a state

Wait Points in Lane Diagrams

A wait point occurs whenever the system sends an event and must wait for a response:

In this diagram:

• W (Wait Point): After sending :payment_request, the system waits → derives #awaiting_payment
• T (Terminal): After receiving :payment_success, the process is complete → derives #confirmed

Why Lane-First?

Benefit	Explanation
Accessible	Non-technical stakeholders understand WHO does WHAT
Complete	All events are mapped before states are considered
Systematic	States are derived, not invented arbitrarily
Collaborative	Full team participates in Sessions 1-2

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

Use Cases for Lane Diagrams

Event Storming Sessions

Print lane diagrams for collaborative design:

eventflow diagram order.flow --type=lane --format=pdf

Stakeholder Communication

Non-technical stakeholders can understand who does what:

• "Customer sends checkout"
• "Order asks Payment to process"
• "Payment responds with success"

API Documentation

Show external integrations:

Best Practices

Limit Lanes

Too many lanes become hard to read. Consider splitting into multiple diagrams:

# Instead of one huge diagram
eventflow diagram system.flow

# Split by scenario
eventflow diagram system.flow --scenario="checkout"
eventflow diagram system.flow --scenario="returns"

Name Events Clearly

Event names appear on arrows - make them readable:

// Good - clear in diagram
emit :payment_authorization_requested to @payment
emit :order_confirmation_sent to @customer

// Avoid - unclear in diagram
emit :req to @payment
emit :msg to @customer

Group Related Actors

In complex systems, group related actors:

┌────────────────────────┬───────────────────────┐
│      Customers         │       Backend         │
├───────────┬────────────┼───────────┬───────────┤
│@web_client│@mobile_app │  @order   │ @payment  │