🏗️ Front-Door Architecture
Front-Door Architecture
Burgundy· Operator Dashboardapps/burgundyReal-time control plane for operators. Manages agents, workflows, approvals, and observability.
Next.js 15React 1985+ RoutesTailwind CSS v4
convex subscriptions + bridge sse↓
Convex· Source of Truthconvex/Durable backend. Stores all registries and run history, interprets workflow DAGs, enforces governance.
117 Tables.lobsterX Interpreter25 Cron JobsGovernance Engine
dispatch↓
Bridge· Execution Routerpackages/bridgeAsync execution router. Loads adapters dynamically, routes dispatch requests, streams events back.
HTTP + SSEPluggable AdaptersCallback Delivery (3x)
results + events↓
OpenClawStateful daemon, MCP, sandboxed execution
Claude Agent SDKClaude Agent SDK, subagent orchestration
▲ Vercel AI
Vercel AI SDK, lightweight structured output
Gloo AI
Auto-routing, grounded completions, tradition
Burgundy Convex Bridge
Gateways
Burgundy
The operator dashboard. Built on Next.js 15 and React 19 with 85+ routes. Operators manage agent registries, launch and inspect workflow runs, triage approvals, and monitor runtime health. Reads durable state from Convex via subscriptions and live gateway state via Bridge SSE. See the Burgundy Dashboard Guide for the full operator experience.
Convex
The durable source of truth. 117 tables store agent definitions, workflow history, governance policies, budgets, audit trails, and more. The interpreter resolves workflow DAGs, dispatches steps through the governance pipeline, and advances execution state. Convex-native agents (Factory Manager, Workers, Copilot) run inside Convex via @convex-dev/agents.
Bridge
The async execution router. Receives dispatch requests from Convex, loads adapters, delegates execution to the target gateway, and calls back with results. Also streams runtime events to Burgundy via SSE. Bridge is a transport seam — it isolates Convex and Burgundy from gateway-specific concerns. A single Bridge instance can load multiple adapters simultaneously (configured via BRIDGE_ADAPTERS), routing each dispatch request to the correct adapter by provider name.
🔌 Gateways
Pluggable execution runtimes. Each gateway has a corresponding Bridge adapter that implements the interface. Currently supported: OpenClaw, Claude Agent SDK, Vercel AI, and Gloo AI. Gateways execute agent sessions, tool calls, and model interactions, then return structured results through Bridge.🔗 Two API Surfaces
Forge exposes two API surfaces. The Dashboard API is a Convex-reactive boundary for UI consumers like Burgundy — 13 domain modules accessed viauseQuery/useMutation subscriptions. The Platform API is a REST surface for external integrations — 42+ HTTP endpoints authenticated with API keys. Both compose from the same internal domain modules in Convex.
API Surfaces
🔗 Dashboard API
Consumer: Burgundy, future UIs
Transport: Convex reactive (useQuery/useMutation)
Auth: WorkOS user tokens
Real-time: Native push-based subscriptions
Modules: 13 domain modules
🔌 Platform API
Consumer: External integrations
Transport: REST/HTTP
Auth: API keys (fgk_*)
Real-time: Polling or SSE
Endpoints: 42+
🔀 Dual Execution Model
Forge runs two categories of agents through different execution paths.Dual Execution Model
Convex-Native AgentsDurable agents running inside Convex via @convex-dev/agents. Persistent threads, tool access, transactional state.
Factory ManagerFactory WorkerTask ManagerCopilot
Direct in Convex — no Bridge
Bridge-Dispatched StepsWorkflow steps dispatched through Bridge to gateway adapters. Stateless per-execution. Full governance pipeline.
.lobsterX StepsDelegated RunsSkill Execution
Convex → Bridge → Adapter → Gateway
Convex-native agents and Bridge-dispatched steps coexist in the same workflows. The interpreter decides the execution path based on step configuration.
📡 Runtime Data Flow
Burgundy maintains two live connections simultaneously:- Burgundy ⇄ Convex: Durable state via
useQuery/useMutationsubscriptions - Burgundy ⇄ Bridge: Gateway operations via REST, live events via SSE
📋 What Forge Does
| Capability Area | What It Covers |
|---|---|
| 🤖 Agent Management | Definitions, deployments, templates, skills, tools, models, sessions, 3-layer memory |
| ⚙️ Workflow Orchestration | .lobsterX YAML DSL, DAG execution, checkpoints with rewind and branch |
| 🛡️ Governance | 10-gate safety pipeline, policies, approval workflows, budget enforcement |
| 📊 Observability | Distributed traces, analytics dashboards, audit trail, alerts, webhooks |
| 🏭 Software Factories | Autonomous production units with Factory Manager agents, teams, budgets, dev environments |
| 💬 Hybrid Workforce Chat | Channels, sessions, messages, multi-agent relevancy gating, Slack syndication |
| 🔌 Platform API | 42+ REST endpoints, OpenAPI 3.1 spec, API key management |
| 📦 TypeScript SDK | Typed client library — @tangogroup/forge-sdk |
| 🧩 MCP Server | Model Context Protocol server — @tangogroup/forge-mcp |
🚀 Go Deeper
Key Concepts
The essential terminology and mental model.
Quick Start
Guided tour through agents, workflows, governance, and the API.
🤖 Agents
Agent definitions, deployments, skills, tools, sessions, and memory.
⚙️ Workflows
The .lobsterX DSL, DAG execution, and checkpoints.
🛡️ Governance
Safety gates, policies, approvals, and budgets.
🔌 API Reference
42+ endpoints with OpenAPI 3.1 interactive playground.