Architecture Overview
OrcFlows is a Go monorepo with three deployable binaries, a SvelteKit frontend, and a set of supporting infrastructure services.
Components
┌─────────────────┐
│ SvelteKit Web │ (web/, port 5173)
│ Canvas + Admin │
└────────┬─────────┘
│ REST + SSE
┌────────▼─────────┐
│ API Server │ (cmd/api, port 3001)
│ chi router │
│ auth, CRUD, │
│ webhooks │
└───┬────────┬─────┘
│ │
┌───────────────┘ └───────────────┐
│ │
┌──────────▼─────────┐ ┌──────────▼──────────┐
│ PostgreSQL │ │ Temporal │
│ tenants, users, │◄──────────────────┤ workflow engine │
│ workflows, secrets, │ step results │ (durable execution) │
│ executions, KB, │ └──────────┬──────────┘
│ embeddings │ │
└──────────────────────┘ ┌──────────▼──────────┐
│ Temporal Worker │
│ (cmd/worker) │
│ runs node Execute() │
│ as activities │
└──────────┬──────────┘
│
┌──────────────┬──────────────┬───────────┼───────────┬──────────────┐
│ │ │ │ │ │
┌─────▼────┐ ┌──────▼─────┐ ┌──────▼─────┐ ┌───▼────┐ ┌────▼─────┐ ┌──────▼─────┐
│ Docker │ │ SearXNG │ │ Chromium │ │ Weaviate│ │ MinIO │ │ LiveKit │
│ Sandbox │ │ (search) │ │(Playwright)│ │ (RAG) │ │ (S3) │ │ (voice/AV) │
└───────────┘ └────────────┘ └────────────┘ └─────────┘ └──────────┘ └────────────┘
API Server (cmd/api)
A chi HTTP router (internal/api) exposing:
- Auth (register/login/SSO/Google sign-in), JWT-based sessions
- Workflow CRUD, versioning, import/export, AI generation
- Execution management (list, detail, retry, cancel, signal, SSE stream)
- Connectors, secrets, OAuth connections
- Knowledge bases, skills
- Team/organization/billing/SSO management
- Public webhook routes (
/webhooks/*) and public workflow APIs (/run/*)
The API server enqueues work onto Temporal but does not execute workflow steps itself.
Temporal Worker (cmd/worker)
Polls two task queues:
goagents-main— workflow orchestration plus heavy steps (agent, code execution, STT/TTS).goagents-fast— lightweight steps that finish in seconds (transform, set, condition, etc.), so they don't queue behind long-running agent activities.
Each node type is registered globally (nodes.GlobalRegistry) and dispatched as a Temporal activity; the workflow itself (RunWorkflow, RunScheduledWorkflow, plus per-channel poller workflows like EmailPollerWorkflow) is a Temporal workflow function that walks the DSL's step DAG, resolves expressions, and calls activities with retry policies derived from each step's timeout/max_retries/retry_delay.
Frontend (web/)
SvelteKit + Svelte 5 (runes) + SvelteFlow for the visual canvas, Tailwind CSS + Lucide icons. Talks to the API server over REST and Server-Sent Events for live execution updates.
Data store: PostgreSQL
A single Postgres database (port 5433 in dev) holds essentially everything: tenants/users/roles, workflow definitions and versions, execution metadata, encrypted secrets and OAuth tokens, knowledge base documents/chunks/embeddings, skills, audit log, billing/subscriptions, and organizations. See Multi-Tenancy & Data Model.
Supporting services
| Service | Purpose | Required? |
|---|---|---|
| Redis | Caching / rate limiting | Recommended |
| SearXNG | Self-hosted search backing the web_search agent tool | For web-search tools |
| Chromium (headless) | Playwright/CDP browser automation | For browser-automation tools |
| Weaviate | Enterprise ANN vector search for large Knowledge Bases | Optional — Postgres embeddings work by default |
| MinIO / S3 | Workspace file storage (generated PDFs, screenshots, uploads) | Recommended |
| LiveKit | Real-time audio/video for voice agents | For livekit-* nodes |
| Temporal + Temporal UI | Durable workflow execution engine + observability UI | Required |