Event Flowing Sessions

Event Flowing is a collaborative methodology for designing, building, and testing event-driven systems using EventFlow. It brings together cross-functional teams to create executable specifications through iterative sessions.

The Core Principle

The diagram is your thinking tool.

Unlike traditional approaches where diagrams are drawn first and then translated to code (where they inevitably drift), Event Flowing makes the diagram an active part of your design process:

1. Write the flow in natural language
2. Watch the diagram evolve as you type
3. Think through the visualization together
4. Refine until the team agrees

The diagram isn't just output - it's where you think through your design.

Remote Sessions

Event Flowing sessions happen remotely. The team joins a video call, and the developer shares their screen showing both the flow file and the live diagram.

The developer (Alex) acts as the "scribe" - writing EventFlow code while the discussion continues over voice. With watch mode enabled, diagrams update automatically:

$ eventflow watch order.flow

  EventFlow v1.0.0

  ➜  Editor:   http://localhost:5173/
  ➜  Diagram:  http://localhost:5173/diagram
  ➜  Tests:    http://localhost:5173/tests

  Watching for changes...

Everyone sees the same diagram. Everyone thinks through the same visualization.

Share Your Flows

Event Flowing sessions produce valuable artifacts. After each session, share the outputs with the broader team:

Interactive HTML Export

$ eventflow export order.flow --format=html --output=./docs/

  Exporting order.flow...
  ✓ Diagram generated
  ✓ Test coverage included
  ✓ Interactive HTML ready

  Output: ./docs/order.html

Host the HTML output on your company wiki, SharePoint, or any static hosting. Now:

• PMs can verify flows before customer meetings
• Support teams can answer "how does this work?" questions themselves
• New team members can explore the system during onboarding
• Stakeholders can review without scheduling developer time

The code changes, the documentation updates automatically - this is EventFlow's core promise.

Automate Documentation Updates

Add HTML generation to your workflow - whether through CI/CD pipelines or push-to-deploy services:

CI/CD Pipeline (GitHub Actions, GitLab CI, etc.):

# In your CI/CD script
eventflow export *.flow --format=html --output=docs/
# Deploy docs/ to your internal documentation site

Push-to-Deploy (Vercel, Netlify, Cloudflare Pages):

# In your build command
eventflow export *.flow --format=html --output=public/flows/

Every push refreshes the documentation. No manual steps, no drift. The diagrams always reflect what's actually in the codebase.

EventFlow as a Thinking Tool

EventFlow isn't just a software tool - it's a thinking tool. Similar to "breadboarding" in Shape Up methodology:

Shape Up Breadboard	EventFlow Equivalent
Places (screens)	#states
Affordances (actions)	:events
Connection Lines	emit ... to @actor

Just like a breadboard shows flow without visual details, EventFlow shows business logic without implementation details.

Fat Marker Sketches

First drafts can be rough - like "fat marker sketches":

scenario: checkout
  on :checkout from @customer (api)
    do payment stuff  // not detailed yet
    order moves to #complete

Then refined:

scenario: checkout
  on :checkout from @customer (api)
    ? cart is not empty
    ? @customer is logged in
      emit :payment_request to @payment
      order moves to #awaiting_payment

Start rough, refine together. The diagram evolves as understanding deepens.

Coming Back After a Break

EventFlow is designed to be easy to pick up again after weeks or months away.

Quick Symbol Refresher

Symbol	What it means	Example
@	Actor (who)	@customer, @payment
:	Event (what happens)	:checkout, :payment_success
#	State (current status)	#pending, #paid
$	Data (context variable)	$total, $items
?	Guard (condition)	? cart is not empty
=	Assertion (verification)	= order is in #paid

Memory trick: @ = at someone, : = something happening (colon like "action:"), # = hashtag status, $ = dollar value

Re-orientation Strategy

1. Start with the diagram - run eventflow watch and look at the visual
2. Read the scenario names - they describe features in plain English
3. Check the given: blocks - they show preconditions
4. Trace one happy path - follow the events through states

Within minutes, you'll remember how the system works.

The Team

Event Flowing works best with a cross-functional team:

Role	Focus	Key Questions
Product Manager	Business requirements	"What should happen when...?"
Developer	Technical implementation	"How do we handle...?"
QA Engineer	Edge cases & quality	"What if...?" / "What could go wrong?"
Designer	User experience	"What does the user see?"

The Flow

A typical Event Flowing engagement follows this pattern across 5 sessions:

Lane-First Design Philosophy

EventFlow follows a lane-first approach to state machine design. This separates concerns appropriately across different team members:

Key insight: States are derived, not invented.

In event-driven systems, a state only exists when the system is waiting for something:

• Waiting for an external event (response from another actor)
• Reached a terminal point (success or failure)

This means:

1. Sessions 1-2 (Full Team): Focus on WHO (actors) and WHAT HAPPENS (events)
2. Session 3 (QA + Dev): Define scenarios based on event behavior
3. Session 4 (Dev Only): Derive states from wait points in the lane diagram

Non-technical stakeholders participate in Sessions 1-3 without needing to understand state machine concepts. States are a technical detail that developers handle in Session 4.

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

Session Types

Session 1-2: Event Flowing (Full Team)

• Identify actors and events together
• Write the flow in natural language
• Think through the diagram as it evolves
• Discuss data and context step by step
• Note edge cases (but don't solve them yet)
• Focus on events, not states

Session 3: Edge Case Discovery (QA + Dev)

• Systematically identify failure scenarios
• Write test cases first (.test.flow)
• Use assume: and observe: for precise testing
• Failing tests become implementation targets

Session 4: Implementation (Dev Solo)

• Derive states from lane diagram wait points
• Update flow to handle edge cases
• Add guards, OR guards, otherwise branches
• Design API responses (reply syntax) - see Machine Responses
• Turn failing tests green
• Choose an implementation approach:
  • Session 4a: Direct Implementation - Write all bindings at once
  • Session 4b: TDD Implementation - Red-Green-Refactor for each binding

Session 5: Review (Full Team)

• Run full test suite with coverage
• Review generated diagrams
• Validate living documentation
• Ship it!

Example: E-commerce Checkout

This guide walks through building an e-commerce checkout flow across 5 sessions:

• Session 1: Discovery - Identifying actors, events, and data
• Session 2: Happy Path - Writing the flow with context
• Session 3: Edge Cases - QA + Dev discover failure scenarios
• Session 4: Implementation - Derive states from wait points
  • Session 4a: Direct - All bindings at once
  • Session 4b: TDD - Red-Green-Refactor cycle
• Session 5: Review - Final testing and ship

The Team for This Example

Throughout these sessions, you'll follow four team members:

• Sarah (Product Manager) - Owns the business requirements, makes scope decisions
• Alex (Developer) - Writes the flows and implements PHP bindings
• Jordan (QA Engineer) - Challenges assumptions, discovers edge cases, writes tests
• Maya (Designer) - Focuses on user experience and state visibility