🏗️ Four-Layer Architecture
System Architecture
Burgundy· Operator Dashboardapps/burgundy — Next.js 15, React 1985+ routes. Reads from Convex (subscriptions) and Bridge (REST/SSE). All pages are client-rendered.
Agent RegistryWorkflow RunsApprovalsObservability
convex subscriptions (useQuery / useMutation)↓
bridge rest + sse↓
Convex Engine· Source of Truth117 tables, workflow interpreter, governance engine, native agents
SchemaInterpreterGovernanceConvex-Native Agents
Bridge· Execution RouterExpress, SSE, adapter loading
DispatchSSE Streaming
dispatch → adapter interface → results + callbacks↓
OpenClawStateful daemon. Agent configs, MCP, sandboxing, workspace files.
Claude Agent SDKClaude Agent SDK. Stateless. Native subagent orchestration.
▲ Vercel AI
Vercel AI SDK. Lightweight, structured JSON output.
Gloo AI
Auto-routing, grounded completions, tradition.
Burgundy Convex Bridge
Gateways
🔀 Dual Execution Model
Forge runs agents through two distinct execution paths depending on the agent type and use case.- Prescriptive Workflow Flow
- Delegated Run Flow
The standard path for workflow execution via Bridge to gateway adapters.
Prescriptive Workflow Flow
Interpreter
→Governance
→Dispatch
→Bridge
→Adapter
→Gateway
→Callback
Steps pass through Bridge to gateway runtimes. Full governance pipeline. Stateless per-execution.
📡 Data Flow
Four communication paths connect the layers. Each serves a distinct purpose.| Path | Protocol | Direction | Purpose |
|---|---|---|---|
| Burgundy ↔ Convex | WebSocket subscriptions | Bidirectional | Real-time reactive queries and mutations. All durable state. |
| Burgundy ↔ Bridge | REST + SSE | Bidirectional | Live gateway state, execution event streaming, agent management. |
| Convex → Bridge → Gateway | HTTP dispatch | Outbound | Step execution requests with governance constraints. |
| Gateway → Bridge → Convex | HTTP callbacks | Inbound | Execution results, token usage, cost data. 3x retry with backoff. |
🔐 Ownership Boundaries
A strict ownership boundary separates what Convex controls from what gateways control.| Concern | Owner | Details |
|---|---|---|
| Workflow definitions | Convex | .lobsterX YAML stored in workflowDocuments, pinned at run start |
| DAG resolution | Convex | interpreter.ts resolves step ordering and parallelism |
| Governance decisions | Convex | 10-gate pipeline in governanceEngine.ts |
| Budget enforcement | Convex | Budget envelopes, agent spend tracking, monthly resets |
| Run history | Convex | workflowRuns, stepResults, tokenEvents, auditEvents |
| Agent registry | Convex | Definitions, deployments, skills, trust levels, role bindings |
| Live execution | Gateway | LLM calls, tool invocation, file I/O, sandboxed code execution |
| Session state | Gateway | Conversation context during a single execution |
| Cost reporting | Gateway | Token counts and cost per execution, reported via callback |
Convex owns all durable state. Gateways own live execution. If a gateway crashes mid-execution, Convex detects the timeout (enforced every 60 seconds by the step timeout cron) and applies the step’s
on_failure policy.💡 Key Design Decisions
Why Convex as the backend?
Why Convex as the backend?
Convex provides three properties that are hard to replicate with traditional stacks:
- Transactional mutations ensure that governance decisions and step state changes are atomic. A step cannot be marked “running” unless the concurrency check passes in the same transaction.
- Reactive subscriptions push state changes to Burgundy instantly. When a step completes, the dashboard updates without polling.
- Durable workflows via
@convex-dev/workflowgive the interpreter crash recovery. If the Convex process restarts, the interpreter resumes from its last checkpoint.
Why a separate Bridge layer?
Why a separate Bridge layer?
Bridge exists because gateways are external processes with their own lifecycle. Bridge handles concerns that should not live in Convex:
- Adapter loading selects the correct runtime implementation at startup.
- SSE streaming requires long-lived HTTP connections incompatible with serverless functions.
- Callback retry ensures result delivery even when Convex is temporarily unavailable.
Why multiple gateway adapters?
Why multiple gateway adapters?
Different execution runtimes have different strengths. OpenClaw provides persistent agent workspaces and MCP server support. Claude Agent SDK provides native subagent orchestration. Vercel AI SDK offers lightweight structured output. Gloo AI provides intelligent model routing, RAG-grounded completions, and tradition-aware responses. The
ExecutionAdapter interface normalizes these differences so the rest of the platform treats gateways uniformly. A single Bridge instance can load multiple adapters simultaneously, routing each dispatch to the correct adapter by provider name.