Architecture

RondoFlow is a local-first, visual orchestration platform for Claude Code agents. You design a Workspace (Canvas) of Assistants (agents), Skills, Safety Rules (policies), and Connections (MCP servers) — plus data-pipeline cards like Output, Email, Condition (router), Structure (Structurer), and Save to DB — then run them as workflows. Under the hood, a Fastify backend starts (spawns) the Claude Code CLI as subprocesses — and can also drive OpenAI and Perplexity through API runners.

This page is for developers and self-hosters who want to understand how the pieces fit together.

The monorepo

RondoFlow is an npm-workspaces monorepo orchestrated by Turborepo. Five packages under packages/ make up the platform — three services that each run independently in development, plus two libraries.

Run them together with npm run dev (Turborepo), or individually:

npm run dev:ui       # Next.js frontend on :3000
npm run dev:server   # Fastify backend on :3001
npm run dev:docs     # Nextra docs on :3002

Tech stack

Node.js 20+ is required.

Repository layout

• rondoflow
  • packages
    • ui
    • server
      • prisma
      • src
        • index.ts
        • routes
        • engine
          • spawner.ts
          • process-manager.ts
          • agent-runner.ts
          • chain-executor.ts
          • run-registry.ts
          • workflow-generator.ts
        • discussion
        • socket
        • auth
        • services
        • skills
        • lib
    • shared
    • catalog
    • docs
  • docker-compose.yml
  • turbo.json
  • package.json

Content catalog

All of RondoFlow’s shipped, extensible content lives in the @rondoflow/catalog package rather than being hardcoded in the UI or server. It is the seam a future community marketplace would plug into.

• What it ships. Agent templates, workspace presets, canvas templates, the built-in skill catalog, and facilitator presets — exported as AGENT_TEMPLATES, WORKSPACE_PRESETS, CANVAS_TEMPLATES, SKILL_CATALOG, and FACILITATOR_PRESETS.
• Source of truth. One folder per item under content/<group>/<id>/ — a manifest.json plus its Markdown sidecar (persona.md for agents and facilitators, SKILL.md for skills). Adding or editing content is a files-only change; no TypeScript edits.
• Validation + codegen. npm run catalog:build reads and validates every item against the Zod schemas in src/schema.ts, then regenerates the committed src/generated/catalog.data.ts. A generated-in-sync test fails if the generated data drifts from content/.
• Browser-safe entry point. Consumers import values and types from @rondoflow/catalog (src/index.ts), which pulls in neither Zod nor fs, so it is safe to import in the browser. The Node-only loader.ts — which does the filesystem reads and validation — must never be imported by index.ts; it is used by the codegen script and tests only.

Both ends consume it: the server seeds facilitators and resolves the skill catalog (Planner, WorkflowGenerator, skill routes), and the UI renders the template/preset galleries and materializes canvas templates.

Request and execution flow

There are two channels between the browser and the server:

• REST for CRUD and queries — creating Assistants, editing Safety Rules, reading runs, Git operations, settings.
• Socket.IO for everything live — running an Assistant or workflow, streaming output, tool-use cards, and approval requests.

Both channels share the same Better Auth session. The Socket.IO middleware validates the session cookie on connection and joins each client to a per-user room (user:<id>), so server-to-client events are scoped to their owner rather than broadcast.

A run looks like this:

1. The UI emits a Socket.IO event (“run this Assistant / workflow”).
2. The server resolves the effective Safety Rule, builds the prompt and MCP config, and asks the ProcessManager to start the agent.
3. The ProcessManager picks a runner (Claude Code CLI by default; OpenAI or Perplexity for API-backed agents) and starts it.
4. The Claude Code CLI is spawned with --output-format stream-json; the spawner parses each stdout line into typed events.
5. Text, tool-use, and tool-result events stream back to the UI in real time. When a tool hits a Safety Rule that requires approval, the run pauses and an approval request is emitted.
6. You approve or reject; on completion the server emits the final result plus token usage and an estimated cost.

Browser (UI :3000)            Server (Fastify + Socket.IO :3001)        Runner
   |                                |                                      |
   |-- REST: CRUD / queries ------->|                                      |
   |                                |                                      |
   |== Socket.IO: run workflow ====>|                                      |
   |                                |-- resolve policy + build prompt      |
   |                                |-- ProcessManager.startAgent -------->|
   |                                |   spawn claude (no shell!)           |
   |                                |   --output-format stream-json        |
   |<== streaming text =============|<-- stdout JSON events ---------------|
   |<== tool-use / tool-result =====|                                      |
   |<== approval request ===========|   (Safety Rule intercepted)          |
   |== approve / reject ===========>|-- respond ------------------------->|
   |<== done + token usage =========|<-- exit -----------------------------|

Server entry point

packages/server/src/index.ts wires the whole backend together. On startup it:

• Ensures the skills directory exists and runs prerequisite checks (a missing CLI is a warning, not a hard stop, unless a check is marked critical).
• Creates a raw HTTP server so Socket.IO can attach before Fastify starts, then registers CORS (scoped to UI_ORIGIN), multipart uploads (50 MB cap), and IP-keyed rate limiting.
• Installs global error and not-found handlers so every response uses the { success, data?, error?, meta? } envelope.
• Loads DB-stored credentials into process.env, initializes Better Auth, then registers the auth routes and the auth middleware that guards all non-public routes.
• Registers every REST route plugin, exposes /api/health (which reports running agents, queued agents, and pending approvals), and attaches the Socket.IO server with its session-validating middleware.
• Starts the Scheduler, registers the engine socket handlers, and runs a watchdog that auto-rejects approvals that time out.

On SIGINT/SIGTERM it shuts down gracefully: it stops the scheduler and the ProcessManager, then calls teardownRuns(allRuns(), 'shutdown', …) over the unified run-registry — finalizing every registered in-flight run (agents, loops, chains, discussions, and pipelines) and writing their terminal DB status, bounded by a 5-second finalize timeout so a slow database can’t block process.exit. (The per-kind loops/chains/pipelines sweep that follows is only a belt-and-braces fallback for any HTTP-started run not in the registry.)

Engine components

The engine lives in packages/server/src/engine/. Each component has a focused role.

Execution core

Configuration and safety

Orchestration and intelligence

Data pipeline

Iterative and memory

Workflow execution (ChainExecutor)

ChainExecutor is more than a parallel agent fan-out. A workflow’s steps each carry a nodeType (agent, structurer, db-save, http-request, or duckduckgo-search), and the executor handles several modes:

• DAG execution. It validates the graph for cycles, runs independent branches in parallel, and passes each step’s output to its successors.
• Non-agent data steps. A structurer step turns upstream prose into a typed StructuredDataset (deterministic parse or AI extraction via StructuredExtractor); a db-save step persists that dataset to the StructuredDataset / StructuredRow Prisma tables, capped at MAX_DATASET_ROWS = 5000 and MAX_DATASET_BYTES = 2,000,000. These run server-side with no Claude agent.
• Transform steps. http-request and duckduckgo-search steps fetch external data inline — an outbound HTTP call or a DuckDuckGo web search, each interpolating the upstream output via {{input}} — and pass the result to the next step. They run server-side during interactive runs, but the headless scheduler’s chain builder (canvas-chain.ts) does not yet emit them, so scheduled runs skip them.
• Conditional branching. Condition (router) cards compile into grouped conditional edges; within an edge group, the first matching branch wins and routes the run onward (honored in both the parallel DAG path and the sequential Director path).
• Director-gated mode. With director: true, the chain runs as a single sequential cursor with the Director quality-gating each step — no parallelism — and can redirect or conclude mid-run.
• Per-step approval. With approvalMode: 'perStep', the run pauses for human approval before each agent step.

For the user-facing canvas cards behind these mechanics — Output, Email, Condition, Structure, and Save to DB — see the Data Nodes guide.

Canvas card types

A Workspace is built from cards (nodes). Beyond the orchestration cards — Start (Spawn), Assistant, Skill, Safety Rule, Connection, Resource, and Note — the canvas adds seven data-pipeline and transform cards:

Operator knobs

A handful of environment variables tune how the engine reaps stalled runs and tears them down — useful for self-hosters.

When the server runs as root with bypassPermissions, it auto-sets IS_SANDBOX=1 so the Claude Code CLI accepts the root invocation. See Configuration for the complete environment reference.

Persistence

All durable state — Workspaces and their cards, Assistants, Skills, Safety Rules, Connections, Conversations (sessions), runs, schedules, structured datasets, memories, and settings — lives in PostgreSQL via Prisma. The schema and migrations are in packages/server/prisma/. Canvas edits auto-save with a short debounce, so the visual Workspace stays in sync with the database without an explicit save step.

Approvals are an intentional exception: they are ephemeral and kept in process memory, expiring if unanswered.

Where to go next