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
    SDK --> API
    API --> Store[(Database)]
    API --> Artifacts[(Blob Store)]
    Worker1[Worker 1] --> API
    Worker2[Worker 2] --> API
    Worker1 --> Provider[Agent Provider]
    Worker2 --> Provider

Crate map

CrateRole
ironflow-coreShell execution, agent providers, cost tracking
ironflow-engineWorkflow handler trait, context, step orchestration
ironflow-apiREST API (axum), routes, SSE events, dashboard serving
ironflow-workerBackground worker that polls and executes runs
ironflow-storeStorage trait + PostgreSQL and in-memory backends
ironflow-authJWT authentication, password hashing, API keys
ironflow-runtimeDaemon features: webhooks, cron triggers
ironflow-artifactsBlob storage for step-produced files
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

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
  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.