Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture Overview

Ironflow follows a client-server architecture with background workers for execution.

Components

graph TD
    Dashboard[Web Dashboard] --> API[API Server]
    CLI[CLI] --> SDK[Rust SDK]
    MCP[MCP Server] --> SDK
    Hooks[Webhooks and cron] --> API
    SDK --> API
    API --> Store[(Database)]
    API --> Artifacts[(Blob Store)]
    Worker1[Worker 1] --> API
    Worker2[Worker 2] --> API
    Worker1 --> Provider[Agent Provider]
    Worker2 --> Provider

The API owns persistence and never executes a workflow itself (except when it resumes a run in local execution mode). Workers poll the API for pending runs, execute the workflow handler locally, and stream steps and logs back. Scaling out means starting more workers. The scaffolded server and the example server run in Workers mode.

ironflow-runtime is a separate, lighter path: a standalone daemon with webhook endpoints and trigger sources that calls ironflow-core operations directly, without a store or an API. See Standalone Runtime.

Crate map

CrateRole
ironflow-coreOperations (Shell, Http, Agent), agent providers, cost tracking, parallelism, dry-run
ironflow-engineWorkflow handler trait, context, step orchestration, FSM-driven run lifecycle, notifications
ironflow-storeStorage trait plus PostgreSQL and in-memory backends, encrypted secrets
ironflow-apiREST API (axum), routes, SSE events, dashboard serving, Reaper
ironflow-workerBackground worker that polls the API and executes runs
ironflow-authJWT authentication, Argon2 password hashing, API keys
ironflow-artifactsBlob storage for files produced by steps
ironflow-runtimeStandalone daemon: webhooks, trigger sources
ironflow-templatesFetch and install workflow templates from Git
ironflow-sdkType-safe Rust client (types generated from OpenAPI)
ironflow-cliCommand-line interface (clap v4)
ironflow-mcpModel Context Protocol server
ironflow-typesShared API envelope types
ironflow-dashboardReact + Vite web UI, embedded into ironflow-api or served from disk

Request flow

  1. A client (dashboard, CLI, SDK, or webhook) sends a request to the API
  2. The API validates authentication, creates a Run in the Store, and returns it
  3. A Worker polls the API, acquires a lease on the Run, and executes the handler
  4. The handler calls steps (ctx.shell(), ctx.agent(), etc.), each persisted as they complete
  5. Events are published via SSE for real-time updates; a client that falls behind gets a lagged event ({"missed": n}) and reloads its state
  6. On completion or failure, the Worker reports the result back to the API

Data flow

Runs and steps are stored in PostgreSQL (or in-memory for development). Artifacts (files produced by steps) are stored in a separate blob store (local filesystem by default). The two are linked by artifact metadata on each step.