Skip to main content

Architecture overview

AgentForge is a TypeScript monorepo (pnpm workspace, Turborepo, Node ESM) that runs model-backed agents under platform controls. Every model call is metered against one Postgres ledger, every long-running unit of work is a Temporal workflow whose payloads carry only ids, and only one process (the gateway) ever holds the model provider key.

This section describes the static architecture: what the deployables are, how the workspace packages depend on each other, what lives in Postgres, how errors are named and mapped to HTTP, and how each deployable is configured.

Design principles visible in the code​

PrincipleWhere the code shows it
Postgres decides, Temporal carries idspackages/db/src/schema.ts comments: "Postgres is the system of record; Temporal carries only ids" (sessions), "Postgres decides" (factory), "Postgres is the source of truth for verdicts" (quality)
One spend ledgerThe usage table: "Single source of truth for spend: a reservation is a row with status reserved"
Fail closedAGENTS_DISABLED parses any value other than 0/false as disabled; the settings.agents_disabled row is read per request; configs refuse credentials a role must not hold
One key holderapps/api, apps/worker (session, factory, exec and quality-exec roles) all refuse ANTHROPIC_API_KEY at startup; only apps/gateway requires it
Provider SDK isolationOnly @agentforge/agent-runtime-claude and @agentforge/sandbox-runner may declare @anthropic-ai/claude-agent-sdk (apps/smoke/test/boundaries.test.ts)
Decorated runtimeagent-core composes "redaction, kill switch, budget (+alerts), limits, runtime" around any AgentRuntime
Strict wire contractsEvery HTTP schema in packages/agent-types/src/http.ts is a z.strictObject (unknown fields are rejected)

The big picture​

Section map​

PageWhat it covers
System contextC4-style context and container diagrams, external systems, ports, trust boundaries
Packages and appsEvery workspace package and app, its responsibility, the dependency graph, turbo boundary tags and the blocking boundary tests
Data modelAll 17 Postgres tables, constraints, migrations 0000 to 0007, and which deployable writes which table
Error modelThe shared ErrorCode enum, Table E (code to HTTP status), Table S (toResponse), Retry-After, Temporal retry semantics, gateway error shapes
ConfigurationEnvironment variables per deployable with defaults, cross-field rules, the _FILE secret convention and refused variables

Deployables at a glance​

DeployableEntryHoldsNever holds
APIapps/api/src/server.ts (dist/migrate.js for migrations)API_KEYS, DATABASE_URL, Temporal client, api control token fileANTHROPIC_API_KEY, worker control token
Session worker (core)apps/worker/src/main.tsDATABASE_URL, worker control token file, TemporalANTHROPIC_API_KEY, GITHUB_APP_*
Exec worker (fleet)apps/worker/src/exec-main.tsTemporal, payload keys, GATEWAY_URLDATABASE_URL, ANTHROPIC_API_KEY, GATEWAY_CONTROL_*, GITHUB_APP_*
Factory workerapps/worker/src/factory-main.tsDATABASE_URL, GitHub App keys, docker access for sandboxesANTHROPIC_API_KEY
Quality exec workerapps/worker/src/quality-exec-main.tsTemporal (quality namespace key), docker socket, local repo mirrorDATABASE_URL, ANTHROPIC_API_KEY, GATEWAY_CONTROL_*, GITHUB_APP_PUSH_*
Gatewayapps/gateway/src/server.tsANTHROPIC_API_KEY, DATABASE_URL, both control tokens, policy and registry dirsGitHub credentials, Temporal
Sandbox runnerapps/sandbox-runner/src/main.ts (inside the per-job container)an afj_ job token as its ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL pointing at the gatewaythe real provider key, Postgres, Temporal

Details, including every variable, are on Configuration. Hosting is covered in Deployment topology.

Where to go next​

Sources​

  • packages/db/src/schema.ts (table comments)
  • packages/agent-core/src/index.ts (createAgentRuntime composition comment), packages/agent-core/src/config.ts
  • packages/agent-types/src/http.ts (strict schemas)
  • apps/api/src/config.ts (loadConfig), apps/worker/src/config.ts (loadConfig), apps/worker/src/exec-config.ts (EXEC_FORBIDDEN), apps/worker/src/factory/config.ts (loadFactoryConfig), apps/worker/src/quality/exec-config.ts (FORBIDDEN), apps/gateway/src/config.ts (GatewayEnv)
  • apps/smoke/test/boundaries.test.ts
  • docs/design-worker-fleet.md, docs/deploy-quality.md (Roles table)