Skip to content
flow8

Core Concepts

Core Concepts

Flow

A flow is a reusable workflow definition stored in MongoDB. It is the template — not the execution. A flow contains:

  • A name, category, and enabled flag
  • An ordered set of flowlets (steps)
  • KV inheritance and conflict settings
  • Execution configuration (timeouts, queue behavior)

One flow can be executed many times. Each execution creates a play.

Flowlet

A flowlet is one step within a flow — a module invocation with specific arguments. Each flowlet has:

  • A ref (unique name within the flow, used in expressions)
  • An appId (which module to run, e.g., curl, chat, pdf-extract)
  • Args (module inputs — can be static values or dynamic expressions)
  • Filters (optional conditions that must be true for the step to execute)
  • Timeout and retry configuration
  • NeedsApproval flag (pauses execution, waits for human sign-off)

Play

A play is one execution instance of a flow. When you trigger a flow, a play is created with a unique ID. It tracks:

  • Current state: NEW → RUN → DONE | FAIL | SKIP
  • Input arguments passed at trigger time
  • The output of every flowlet
  • Start time, completion time, and duration

Plays are permanent records — they are never modified after completion, only retained or cleaned up per retention policy.

Module

A module is a unit of work. flow8 includes 135+ built-in modules across categories:

  • Control flow (Router, Iterator, Aggregator, Subflow)
  • Data transformation (Template, Regex, JSON, CSV, Array)
  • HTTP & Network (cURL, Wget)
  • AI (Chat, Embeddings, Structured Extract)
  • Storage (Read, Write, S3, Google Drive)
  • Database (Query, Insert, MongoDB, PostgreSQL)
  • Email & Messaging (SMTP, IMAP, Slack)
  • Document processing (PDF, OCR, LibreOffice)
  • Cryptography (AES-GCM, HMAC, JWT)
  • External integrations (Clio, QuickBooks, Microsoft Graph, Google Sheets, and more)

Expression

Expressions are dynamic values embedded in flowlet arguments. They are evaluated at runtime using the execution context.

Syntax: {{ expression }} (Go template style) or XPath for document navigation.

Available in expressions:

  • $prev.<ref>.<field> — output from a previous flowlet by its ref name
  • $kv.<key> — value from the KV store
  • $date.now() — current datetime
  • $rand.uuid() — random UUID
  • Standard operators: arithmetic, string, comparison, array functions

Example: an email subject that includes the result of a previous step:

"Invoice {{ $prev.generateInvoice.invoiceNumber }} ready for review"

KV Store

The KV store provides scoped key-value persistence that survives across executions. Scopes:

  • global — shared across all flows in the company
  • flow_group — shared across all flows in a group
  • flow — private to one flow

KV values are encrypted at rest. Use them for counters, flags, last-run timestamps, or data shared between flows.

Channel

A channel is an inbound endpoint that triggers flows. Channels can be:

  • HTTP — a REST endpoint on a custom port (e.g., webhook receiver)
  • WebSocket — streaming input/output
  • MCP — Model Context Protocol, exposes flows as tools for AI agents

Each channel has routes that map incoming requests to target flows.

Component

A component is a swappable runtime capability. Instead of hardcoding which AI provider or storage backend a module uses, modules request a component by kind (ai, storage, db, request). The platform resolves which implementation to use based on configuration — and this can be overridden per flowlet.

This means you can switch from OpenAI to Anthropic for a specific step, or use S3 for one module and local storage for another, without changing the flow definition.