What is EventFlow?

EventFlow is a natural language DSL where the documentation you write IS the executable state machine. There is no code generation step - the .flow files are directly interpreted at runtime.

The Core Idea

machine: @order

scenario: complete purchase

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

  on :payment_success from @payment
    order moves to #paid

  expect:
    = order is in #paid

This is not pseudocode. This runs.

One File, Three Outputs

Every .flow file serves as a single source of truth that produces:

• Runtime: Your state machine executes exactly as written
• Tests: Every scenario with assertions is an executable test
• Diagrams: Visualizations are auto-generated from the same source

Zero drift. Always in sync.

Who Uses EventFlow?

EventFlow brings together different roles in collaborative sessions:

Role	How They Use EventFlow
Product Managers	Define business flows and validate logic
Developers	Implement bindings and maintain runtime
Designers	Understand user journeys and states
QA Engineers	Write test scenarios and verify behavior

From Event Storming to Running Code

Traditional workflow:

EventFlow workflow:

Core Concepts at a Glance

Machines and Instances

A machine in EventFlow is a template - a definition of behavior:

machine: @order    // This is a TEMPLATE

When events arrive, instances (also called aggregates) are created:

@order (machine/template)
  ├── @order:abc123 (instance/aggregate)
  ├── @order:xyz789 (instance/aggregate)
  └── @order:def456 (instance/aggregate)

• First event creates a NEW instance with a unique ID
• Subsequent events route to an EXISTING instance
• Each instance has its own state and context

This event-sourced architecture means you define the behavior once, and the runtime manages potentially thousands of independent instances.

Machines are Actors

Every machine is an actor that:

• Has its own state
• Listens for events
• Emits events to other machines
• Manages its own context (data)

machine: @order          // Actor definition

Scenarios are Features

A scenario groups related event handlers that together form a business capability:

scenario: checkout flow

  on :checkout from @customer (api)    // Event 1
    ...

  on :payment_success             // Event 2
    ...

Events Drive Everything

Every state transition is triggered by an event:

on :checkout from @customer (api)      // External event (API)
  order moves to #awaiting_payment

on :payment_success from @payment // Internal event
  order moves to #paid

Natural Language Syntax

EventFlow reads like English:

? cart is not empty              // Guard (condition)
  $total increases by $item.price  // Action
  order moves to #processing       // State transition
  emit :notification to @admin     // Event emission