AI Workforce OS Architecture

Components#

All business state lives in the backend; the runtime keeps no state between calls. Postgres, Redis, object storage and the sandbox are optional in development and each has a fallback.

Backend and runtime boundary#

The core rule: the runtime never talks to Postgres, Redis or external systems. It receives a task with its context and returns a result, tool requests and usage; it only contacts the model provider. The backend decides permissions, autonomy and budget, and is the only one that executes tools.

The backend calls the runtime over HTTP with JSON at RUNTIME_URL. If RUNTIME_TOKEN is set on both sides, every call carries that secret as a bearer token. The AI engine sits behind an interface of its own (AgentEngine), so CrewAI can be replaced without touching the backend.

Request flow#

The user's ask reaches the orchestrator, which asks the runtime for a plan, validates it and creates tasks. Each task is run by an agent that may request tools; sensitive actions wait for human approval, and a report is synthesized at the end.

1. The user submits text with POST /api/v1/requests (or through chat, which routes it). The backend answers 202 with request_id and emits request.received.
2. The orchestrator asks the runtime for a plan and validates it before accepting it: duplicate keys, unknown or circular dependencies and maximum depth. It then emits plan.created and task.created.
3. Tasks run respecting depends_on. Each one changes the agent state (agent.state_changed) and may trigger agent consultations (message.sent) and a quality review (task.reviewed).
4. Tools requested by the runtime go through the autonomy policy and permissions. If approval is needed, a pending record is created (approval.requested) and the task enters awaiting_approval.
5. A user with permission decides with POST /api/v1/approvals/{id}/decision. The task resumes or is blocked.
6. When all tasks finish, the runtime synthesizes the report and the backend emits report.created and request.completed.
7. In parallel, the cost of every call is recorded and the budget is enforced: budget.warning warns and budget.exceeded pauses execution.

POST /api/v1/requests {"text": "..."}      -> 202 {"request_id": "..."}
  orchestrator -> runtime POST /v1/plan          -> tasks + depends_on
  backend validates the plan                     -> plan.created, task.created*
  per task: runtime POST /v1/run-task            -> output, consults, tool_requests, usage
  tool_requests -> policy/autonomy check         -> approval.requested (if needed)
  POST /api/v1/approvals/{id}/decision           -> approval.resolved, task resumes
  runtime POST /v1/synthesize                    -> report.created, request.completed

Realtime channel#

GET /ws opens one WebSocket per organization. The backend publishes each event to Redis (channel aiworkforce:events) and a hub forwards the frame only to clients whose org_id matches; a frame without org_id is dropped. A frame with an audience reaches only those users.

On connect a hello event carries the agent list, followed by domain events. There is no replay, so the client must reload state over REST after reconnecting.

• The server pings every 30 s and closes if no pong arrives within 60 s.
• A slow client, with 256 frames queued, is disconnected.
• With authentication on, the socket closes with code 4401 after 15 minutes (the default access-token lifetime) so the client reconnects with a fresh token.

{
  "id": "<uuid>",
  "type": "task.completed",
  "ts": "2026-01-01T12:03:22Z",
  "org_id": "<org id>",
  "agent_id": "sales",
  "payload": { "task": { "id": "...", "status": "done" } }
}

Data model at a glance#

Tables live in Postgres and every business table carries org_id. This is the summary view; the full schema is in the numbered migrations under backend/internal/infrastructure/postgres/migrations/.

Multi-tenancy#

The org_id travels inside the access token and is never taken from client input. The HTTP layer puts it in the request context and every query is filtered by it. A user can belong to several organizations and switches between them by opening a new session.

As defense in depth, Postgres enforces row-level security:

• Each transaction sets app.org_id with set_config(..., true), local to the transaction; the policies compare org_id with app_current_org().
• If the value is missing, queries see and write no rows: they fail closed.
• The application runs SET ROLE to a non-owner role (DB_APP_ROLE, default app_user, without BYPASSRLS); migrations use MIGRATE_DATABASE_URL.
• The WebSocket hub also filters by organization.

Simulation versus real AI#

The runtime's HTTP contract is the same in both modes; the engine changes. In simulation (with SIMULATION=true or with no provider configured) the runtime returns scripted results with simulated latencies, with no network and no cost. In live mode it uses the configured providers and its GET /healthz reports mode: live and the provider.

If a provider is configured but the live engine cannot start, the runtime answers in simulation with status: degraded and a warning; there is no silent fallback. The backend reflects the mode in its own GET /healthz as runtime_mode.

curl http://localhost:8080/healthz
# {"status":"ok","runtime":"up","runtime_mode":"simulation"}

Deployment and edge#

There are three Compose files:

• docker-compose.yml: development with accounts. Starts postgres, redis, objects (S3 storage), agent-runtime, backend and frontend; the sandbox runner is in the sandbox profile.
• docker-compose.demo.yml: layered on the previous one for the open demo mode (AUTH_ENABLED=false).
• docker-compose.prod.yml: production. caddy, postgres, redis, agent-runtime, backend and frontend; only Caddy publishes ports (80 and 443).

Repository layout#

The backend is layered: api depends on application, which depends on domain; infrastructure implements the ports.

backend/            Go (chi)
  cmd/server/       main.go: composition root (wires every service)
  cmd/sandbox-runner/  code-execution runner
  internal/         domain/ application/ api/ auth/ events/ projects/ drive/
                    skills/ memory/ rewards/ connections/ controls/ audit/ ...
  internal/infrastructure/{postgres,redis,runtime,memory}
  internal/infrastructure/postgres/migrations/   numbered SQL migrations
agent-runtime/      Python FastAPI (CrewAI engine, simulation engine)
  app/              main.py, engine.py, simulation.py, crewai_engine.py, providers.py ...
frontend/           Next.js + React Three Fiber (src/app, src/components, src/lib)
e2e/                Playwright
sandbox/            sandbox container images
Caddyfile           production edge (TLS, reverse proxy)
docker-compose.yml  dev stack; docker-compose.demo.yml, docker-compose.prod.yml
docs/               SPEC.md and architecture/*.md
landing/            this public site