Skip to main content
Forge is a hybrid workforce orchestration platform. This section is for engineers who want to build on, into, or around it — whether that means adding a new gateway adapter, extending the Convex schema, writing a Convex-native agent, or contributing to the Forge Console.
This is the engineering-facing companion to the Platform Overview. That page explains what Forge does. This page explains how the codebase is organized and how to work in it.

​
Monorepo Structure

Forge is a Turborepo + pnpm workspace monorepo. Four top-level directories contain everything. 
gloo-forge/
├── convex/                        # Convex backend (THE source of truth)
│   ├── schema.ts                  # Root schema — imports from schema/
│   ├── schema/                    # Individual table definitions (87+ files)
│   ├── interpreter.ts             # .lobsterX workflow engine (2200+ lines)
│   ├── dispatch.ts                # Step dispatch with governance gates
│   ├── safetyGates.ts             # Gateway health, concurrency, budget gates
│   ├── validation.ts              # LobsterX validation + output coercion
│   ├── gateways/                  # Gateway interface + capability routing
│   ├── agents/                    # Convex-native agent implementations
│   │   ├── factory.ts             # Factory Manager (Overseer) agent
│   │   ├── task_manager.ts        # Task Manager agent
│   │   └── analysis.ts            # Copilot run analysis agent
│   ├── lib/                       # Shared internal libraries
│   │   ├── governanceEngine.ts    # Governance pipeline orchestrator
│   │   ├── gates.ts               # Pre-dispatch gate functions (pure)
│   │   ├── roleResolver.ts        # Role resolution for governance
│   │   ├── rls.ts                 # Row-level security helpers
│   │   └── auth.ts                # Auth utilities
│   ├── chat/                      # Hybrid Workforce Chat system
│   ├── notifications/             # Notification bus + Slack integration
│   ├── ops/                       # Operational support (diagnostics)
│   ├── integrations/              # External services (exe.dev)
│   ├── platformApiRoutes/         # Platform HTTP API (13 route modules)
│   ├── seed/                      # Dev seed data
│   └── crons.ts                   # Scheduled jobs (health, retention)
│
├── apps/
│   └── burgundy/                  # Forge Console (operator dashboard)
│       ├── public/forge/icons/    # Section icons (anvil, bell, flame, etc.)
│       ├── src/app/               # App Router pages (85+ routes)
│       ├── src/providers/         # React context providers
│       ├── src/hooks/             # Custom React hooks
│       ├── src/lib/               # Navigation config, utilities
│       └── next.config.ts         # Rewrites + redirects routing layer
│
├── packages/
│   ├── shared/                    # @tangogroup/shared — types, Zod schemas
│   ├── bridge/                    # @tangogroup/bridge — async execution router
│   ├── bridge-client/             # @tangogroup/bridge-client — React hooks
│   ├── adapter-openclaw/          # @tangogroup/adapter-openclaw
│   ├── adapter-claude-sdk/        # @tangogroup/adapter-claude-sdk
│   ├── adapter-vercel-ai/         # @tangogroup/adapter-vercel-ai
│   ├── forge-mcp/                 # @tangogroup/forge-mcp — MCP server
│   ├── ui/                        # @gloo/ui — shared React components
│   └── tsconfig/                  # @tangogroup/tsconfig — shared TS configs
│
├── docs/                          # Architecture docs, PRDs, reference
│   ├── architecture/              # Architecture docs + flow diagrams
│   ├── principles/                # Engineering principles + standards
│   ├── prds/                      # Capability PRDs
│   ├── reference/                 # Bridge, Forge Console, agents guides
│   └── operations/                # Runbooks, troubleshooting
│
├── turbo.json                     # Turborepo task config
├── biome.json                     # Linter + formatter (NOT ESLint)
└── pnpm-workspace.yaml            # Workspace definitions
Convex module files must use underscores (factory_manager.ts), not hyphens. Convex paths cannot contain hyphens. All other files use kebab-case.

​
Package Dependencies

Every package has a clear dependency direction. Circular dependencies are not permitted.

Package Dependency Graph

@tangogroup/shared

Foundation — types, Zod schemas, .lobsterX schema. No internal deps.

^
@tangogroup/bridge

Depends on shared

@tangogroup/bridge-client

Depends on shared

@tangogroup/forge-mcp

Depends on shared

^
OpenClawadapter-openclaw

Depends on bridge

Claudeadapter-claude-sdk

Depends on bridge

adapter-vercel-ai

Depends on bridge

^
Forge Console@gloo/web (Forge Console)

Depends on bridge-client, shared, ui

@gloo/ui

Standalone React components

Convex@convex-dev/agentsConvex component, used by convex/agents/
Packages use barrel exports (index.ts). Import from the package name, not deep paths: 
// Correct
import type { LobsterXStep } from "@tangogroup/shared";

// Wrong -- never import from internal paths
import type { LobsterXStep } from "@tangogroup/shared/src/lobsterx-schema";

​
Tech Stack

LayerTechnologyVersion
BackendConvexConvex (serverless DB + functions + workflows)Latest
Convex Agents@convex-dev/agents (durable agent framework)Latest
FrontendNext.jsNext.js (App Router), React, Tailwind CSS, Phosphor Icons15 / 19 / v4
LanguageTypeScript (strict mode, noUncheckedIndexedAccess, verbatimModuleSyntax)5
MonorepoTurborepo + pnpm workspacesLatest
Linter / FormatterBiome (not ESLint, not Prettier)Latest
TestingVitestLatest
AuthWorkOSWorkOS AuthKitLatest
Package RegistryGitHubGitHub Packages (@tangogroup/* scope)—
Workflow Format.lobsterX (custom YAML DSL, Zod-validated)—
MCP@tangogroup/forge-mcp (Model Context Protocol server)—
Dev Environmentsexe.dev (cloud VMs for software factories)—
No any in TypeScript. Use existing types, create interfaces, or use unknown / Record<string, unknown>. If truly unavoidable, add a biome-ignore comment with a reason.

​
Build & Run

All commands run from the monorepo root. 
pnpm install              # Install all dependencies
pnpm build                # Build all packages (Turborepo)
pnpm dev                  # Start all services in dev mode
pnpm lint                 # Lint all packages (Biome)
pnpm test                 # Run all tests (Vitest)
pnpm format               # Format all files (Biome)

​
Environment Variables

The build depends on these environment variables (declared in turbo.json):
VariablePurpose
WORKOS_API_KEYWorkOS authentication
WORKOS_CLIENT_IDWorkOS client identifier
WORKOS_COOKIE_PASSWORDWorkOS session encryption
BRIDGE_URLBridge connection URL
NEXT_PUBLIC_BIFROST_URLPublic Bifrost endpoint
Convex environment variables are set in the Convex dashboard, not in .env files. Never commit .env files.

​
Turborepo Task Graph

Turborepo orchestrates the build pipeline. Tasks with dependsOn: ["^build"] wait for upstream package builds to complete first.
TaskCacheDependenciesOutputs
buildYes^build (upstream packages first).next/**, dist/**
devNo (persistent)None—
lintYesNone—
testYes^build—
type:checkYes^build—
formatNoNone—

​
Workspace Layout

The pnpm workspace includes four package roots: 
packages:
  - "packages/*"     # Shared libraries, bridge, adapters, UI
  - "services/*"     # Standalone services
  - "apps/*"         # Forge Console (burgundy)
  - "tests/convex"   # Convex test harness

​
Engineering Deep Dives

Interpreter Deep Dive

The 2200-line .lobsterX workflow engine. DAG resolution, step dispatch, condition evaluation, and failure handling.

Trust Fabric Internals

Governance pipeline architecture. Gates, role resolution, policy evaluation, and the GovernanceDecision type.

Writing Adapters

How to implement the ExecutionAdapter interface and register a new gateway runtime.

Schema Patterns

Convex schema conventions. Table definitions, index naming, optional fields, and migration awareness.

Convex-Native Agents

Building durable agents with @convex-dev/agents. Factory Manager, Task Manager, and Copilot patterns.

Data Flow End-to-End

Tracing a workflow step from .lobsterX YAML through governance, Bridge, gateway execution, and callback.