Skip to main content

Overview

flow-state.dev is a block-based AI workflow framework for TypeScript. You compose four block primitives into flows. The framework runs them, streams the output, and manages state. This page is a map, not a textbook.

Four block kinds​

Every piece of logic is exactly one of four kinds:

  • Handler — Pure logic. Validate input, transform data, mutate state, implement tool logic. No LLM, no streaming. Silent by default.
  • Generator — LLM calls. The framework manages prompt assembly, tool loops, streaming, and structured output. This is where AI happens.
  • Sequencer — Compose blocks into pipelines. Chain steps, run work in parallel, add rescue boundaries for error recovery.
  • Router — Dispatch to different blocks at runtime based on input or state. Mode switching, intent routing, conditional flows.

All blocks share the same typed contract: input in, output out. Any block composes with any other. Chain them in sequencers, nest them in routers, pass them as tools to generators.

Flows tie everything together​

A flow defines your API: actions (entry points), state schemas, resources, clientData, lifecycle hooks. Register a flow with the server and you get REST endpoints for action execution, session management, SSE streaming, and state snapshots. No route wiring.

See Flows and Actions.

State in four scopes​

State lives in four nested scopes with atomic operations:

ScopeLifetime
RequestSingle action run
SessionAcross requests in a conversation
UserAcross sessions for a user
ProjectShared across sessions in a project

Each scope supports patchState, setState, incState, pushState, atomicState. Operations are CAS-guarded. Blocks declare only the state fields they need.

See State and Scopes.

Streaming is structural​

Streaming is not raw text. The framework streams typed items — messages, reasoning, tool calls, state changes, custom components. Each item has a type, a lifecycle (added → content.delta → done), and a sequence number. Clients can disconnect and resume from a cursor. No data loss.

See Items and Streaming.

Everything composes​

Blocks inside blocks. Sequencers as tools. Routers dispatching to sequencers. Type safety from flow definition through the client SDK to React hooks. One Zod schema, validated at runtime and inferred at compile time.

Next steps​