Overview

The Flows feature is a durable, observable execution engine designed to automate business logic. It enables complex branching, parallel execution, delays, and external integrations (webhooks).

Core Philosophy

• Durability: Every step persisted to database for observability and replayability
• Resilience: Built-in retry logic with configurable timeouts
• Visibility: Fine-grained tracking of node inputs, outputs, and errors
• Safety: Guardrails to prevent infinite loops and runaway resource consumption

Key Components

File Structure

features/flows/
├── flow-execution.engine.ts   # Main execution engine
├── flow-repo.ts              # Database operations
├── flow.handler.ts           # Hono route handlers
├── definitions.ts            # Node type definitions
├── validation.ts             # Flow validation
├── services/
│   ├── record.service.ts         # CRUD operations
│   ├── webhook-client.ts         # HTTP client
│   ├── flow-version.service.ts   # Version management
│   └── create-flow.service.ts    # Flow creation
├── types/
└── tests/

Quick Navigation

• Execution Engine — Graph traversal and safety guardrails
• Persistence & State — Schema architecture and idempotency
• API Reference — Execution and replay endpoints
• Node System — Standard node types and patterns

How It Works

1. Trigger: Flow executed via API or event (e.g., record created)
2. Initialize: Create FlowRun with trigger event data
3. Traverse: Execute nodes sequentially or in parallel
4. Persist: Each node creates FlowExecutionNode record
5. Complete: Mark run as COMPLETED or FAILED
6. Retry: Failed nodes can be retried or sent to dead-letter queue