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
| Principle | Where the code shows it |
|---|---|
| Postgres decides, Temporal carries ids | packages/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 ledger | The usage table: "Single source of truth for spend: a reservation is a row with status reserved" |
| Fail closed | AGENTS_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 holder | apps/api, apps/worker (session, factory, exec and quality-exec roles) all refuse ANTHROPIC_API_KEY at startup; only apps/gateway requires it |
| Provider SDK isolation | Only @agentforge/agent-runtime-claude and @agentforge/sandbox-runner may declare @anthropic-ai/claude-agent-sdk (apps/smoke/test/boundaries.test.ts) |
| Decorated runtime | agent-core composes "redaction, kill switch, budget (+alerts), limits, runtime" around any AgentRuntime |
| Strict wire contracts | Every HTTP schema in packages/agent-types/src/http.ts is a z.strictObject (unknown fields are rejected) |
The big picture
Section map
| Page | What it covers |
|---|---|
| System context | C4-style context and container diagrams, external systems, ports, trust boundaries |
| Packages and apps | Every workspace package and app, its responsibility, the dependency graph, turbo boundary tags and the blocking boundary tests |
| Data model | All 17 Postgres tables, constraints, migrations 0000 to 0007, and which deployable writes which table |
| Error model | The shared ErrorCode enum, Table E (code to HTTP status), Table S (toResponse), Retry-After, Temporal retry semantics, gateway error shapes |
| Configuration | Environment variables per deployable with defaults, cross-field rules, the _FILE secret convention and refused variables |
Deployables at a glance
| Deployable | Entry | Holds | Never holds |
|---|---|---|---|
| API | apps/api/src/server.ts (dist/migrate.js for migrations) | API_KEYS, DATABASE_URL, Temporal client, api control token file | ANTHROPIC_API_KEY, worker control token |
| Session worker (core) | apps/worker/src/main.ts | DATABASE_URL, worker control token file, Temporal | ANTHROPIC_API_KEY, GITHUB_APP_* |
| Exec worker (fleet) | apps/worker/src/exec-main.ts | Temporal, payload keys, GATEWAY_URL | DATABASE_URL, ANTHROPIC_API_KEY, GATEWAY_CONTROL_*, GITHUB_APP_* |
| Factory worker | apps/worker/src/factory-main.ts | DATABASE_URL, GitHub App keys, docker access for sandboxes | ANTHROPIC_API_KEY |
| Quality exec worker | apps/worker/src/quality-exec-main.ts | Temporal (quality namespace key), docker socket, local repo mirror | DATABASE_URL, ANTHROPIC_API_KEY, GATEWAY_CONTROL_*, GITHUB_APP_PUSH_* |
| Gateway | apps/gateway/src/server.ts | ANTHROPIC_API_KEY, DATABASE_URL, both control tokens, policy and registry dirs | GitHub credentials, Temporal |
| Sandbox runner | apps/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 gateway | the real provider key, Postgres, Temporal |
Details, including every variable, are on Configuration. Hosting is covered in Deployment topology.
Where to go next
- Request handling and the REST surface: Runtime overview and REST API.
- The gateway and job tokens: Security overview.
- The software factory: Factory overview.
- CodeCrucible mutation testing: Quality overview.
Sources
packages/db/src/schema.ts(table comments)packages/agent-core/src/index.ts(createAgentRuntimecomposition comment),packages/agent-core/src/config.tspackages/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.tsdocs/design-worker-fleet.md,docs/deploy-quality.md(Roles table)