Proposal: EventFlow Lane Diagrams

Status: Draft - For Discussion

Inspiration: BPMN Sketch Miner

BPMN Sketch Miner uses a text-based approach where each line becomes a diagram element. We adapt this for EventFlow with our symbol system.

---

Example: E-commerce Checkout with Guards and Actions

---

Corresponding EventFlow Code

machine: @order

@customer
>on :checkout
  ? customer is logged in
    :login_required -> @customer
  ? cart is not empty
    :empty_cart -> @customer

  $order_id = uuid()
  $total = calculate()

  :request_payment -> @payment ($order_id, $total)

@payment
on :request_payment
  ? payment successful
    :payment_complete -> @order
  ?
    :payment_failed -> @order

@order
on :payment_complete
  send confirmation email
  :order_confirmed -> @customer
  :ship_order -> @shipping ($order_id, $address)

@shipping
on :ship_order
  (preparing)
  :shipped -> @order

@order
on :shipped
  :shipment_notification -> @customer

on :delivered
  :delivery_confirmed -> @customer

---

Visual Elements Mapping

EventFlow	Diagram Element
@actor	Lane (column)
:event	Arrow with label
>on :event	Trigger dot + arrow (API)
on :event	Arrow (internal)
? condition	Diamond with ?
$var = value	Box with assignment
-> @actor	Arrow to actor's lane
Success	Green arrow
Error/rejection	Red arrow

---

Alternative: Flow Chart Style (No Lanes)

A simpler view without actor lanes - just the flow of events, guards, and actions. Actors shown as labels on events.

---

Key Benefits

1. All elements visible - Guards, actions, events in one diagram
2. Flow is clear - Top to bottom, left to right for responses
3. Matches code - Diagram structure mirrors .flow file structure
4. Team readable - Non-developers can follow the logic