Where humans approve
Between the plan and any outward effect. Deployer-level approval gates commit/push, S3, Content Bundles and Jira transitions.
Architecture portal
One platform,
from core to control.
Forge is a layered system. Each layer has a single responsibility, a stable contract to the layer above, and a clear boundary it will not cross. Models sit at the core and are replaceable; the human control plane sits at the top.
1
Explore
Interactive systems map
Select any systemto see why it exists, what it owns, how it works, and its key boundary.
Click a node ↓2
The stack
Layered model — core outward
Layer 1
Model & inference
Open-weight local models and a cloud specialist behind a capability contract — seven lanes (fast · reason · code · review · vision · plan · embed) routed with a competence floor; only reason and code may burst to cloud.
Boundary: replaceable — swap a model and nothing above changes.
Layer 2
Knowledge, memory & retrieval
Semantic — workspace-scoped RAG grounds reasoning in real production context, in one of two modes validated by deployment_config (fail-closed): local (JSONL + on-device embeddings) or hybrid (PostgreSQL + pgvector with an EmbeddingContract and row-level security). The knowledge base is ground truth; the index is a derived overlay. See ADR-0001.
Structural — the Code Intelligence Engine (ADR-0003) adds a code graph: impacted symbols, call chain and blast radius answer what a change touches. It runs structural-first and LLM-free to bound the search space, then scopes RAG to the blast radius — fewer, better chunks (fewer tokens, better fixes). Graphify is the first provider behind a swappable seam; a structural re-ranker fuses graph proximity with embedding recall. In hybrid mode the raw index never leaves the authenticated worker — only trust-tagged evidence crosses to the control plane.
Boundary: structural findings enter as derived evidence and retrieved chunks as untrusted reference — both ground reasoning but neither authorises, and neither is ever a deterministic gate; missing evidence stays missing.
Layer 3
Fabric agentic runtime
Context assembly, reasoning, tool execution and runtime events — the engine that turns a plan into observable work.
Boundary: no product-UI responsibilities live here.
Layer 4
Decision & policy
Pure, auditable routing, confidence, preconditions, roles and retry.
Boundary: confidence never overrides a hard validation, policy or permission failure.
Layer 5
Tool & integration
Eleven integrations, each behind a shared resilience wrapper: Perforce, Jira, Confluence, GitHub (GHE) → S3, Photoshop, Unity (live MCP bridge), Google Sheets, Bugsnag (SmartBear MCP), Datadog, Slack, plus future MCP endpoints.
Boundary: irreversible work is never retried blindly; a failed source stops the run.
Layer 6
Execution & orchestration
Four runtimes (generic · unity · offer · data), stage dispatch, queue, streaming and worker execution.
Boundary: a capability runs only where an executor supports its mode and runtime.
Layer 7
Agent & pipeline definition
The JSON contract — stages, grounding, policies, validators, gates — that is the single source of truth.
Boundary: behavior is read/written only through validated JSON.
Layer 8
Forge APIs & platform services
The HTTP router, NDJSON run streams, workspaces and the security boundary (origin/host/CSRF, tokens, roles, audit).
Boundary: unknown users, roles and action classes fail closed.
Layer 9
Forge Studio & UX
Visual authoring, Pipeline, Mission Control, Weave and explainability — the human control plane.
Boundary: presents and composes; never executes tools directly.
Layer 10
Governance, observability & enterprise controls
Harness certification, approvals, telemetry, health, run journal, post-mortems and the Character definition-of-done — cross-cutting every layer.
Boundary: a readiness score explains; hard gates and human sign-off remain binding.
3
Cross-cutting
How trust & evidence move
How Studio becomes runtime
Studio compiles the graph to agent JSON; the runtime reads that JSON and dispatches stages; run events stream back to the Studio canvas live.
How evidence & audit flow
Forge authorities emit server-attested, workspace-scoped facts to the Canonical Forge Event Spine. Its signed, hash-chained bus feeds Operation Rooms, Search & RAG, audit and the live UI as read-only projections; none can execute or approve work.
Failure & security boundaries
Connectors fail honestly; the security layer classifies every request; unresolved values and unsupported executors stop the run.
Portable agents — the Agent Store
Commissioned agents export as checksum-sealed forge.agent-package.v1 bundles — portable workflow graph, profile metadata and permitted local skills, with credential-shaped fields stripped and traversal/oversized archives rejected. Preview is a bounded read; installation is a separate admin-gated action that never grants credentials, tool access, production routing or commissioning authority.
4
Event architecture
Canonical Forge Event Spine
Every governed command reaches an execution authority through the Forge Gateway and policy boundary. The resulting facts converge on the canonical Forge Event Bus, which projects the same signed evidence into operation rooms, retrieval, audit timelines and the live UI without granting those read models execution authority.
Current delivery is not historical health
Operation Rooms reports the current process delivery state separately from retained projection gaps. A healthy publisher therefore stays green even when an older read-model delivery still needs operator review.
Reconciliation never replays work
A projection-gap acknowledgement preserves the original dead-letter record and appends a signed, workspace-scoped operator fact. It does not retry a connector, resume a run, approve work, publish an agent or alter execution state.
Evidence remains tamper-evident
Canonical events are server-generated and hash-chained. Gap acknowledgements name their original occurrence, actor, workspace and reason so audit can distinguish a repaired projection from a repeated side effect.
Retries remain adapter-specific
Idempotency reduces duplicate effects only where an adapter can reconcile external state. Unknown-completion cases remain stopped until the external system is checked and a new governed action is explicitly authorized.
5
Production intelligence
Production Knowledge Graph & GraphRAG
A workspace- and game-scoped read-only projection that connects tickets, Perforce sources, Unity assets, workflows, runs, artifacts, builds, incidents and owners into one governed graph. It federates existing authorities — Graphify stays the AST graph, workflow DAGs stay the executable definitions, and the Event Spine stays the authoritative execution record — and answers only bounded, typed questions, never free-form model-generated queries.
Federates, never replaces
Graphify stays the AST graph, workflow DAGs stay executable definitions, and the Event Spine stays the authoritative execution record. The graph is a projection over those authorities — with revision and provenance on every fact.
Trust is explicit
Every fact carries an authoritative, derived or hypothesis trust class. Retrieval is trust-labelled, so grounding never silently promotes a guess to fact.
Bounded, typed, auditable
Only typed operations run — ticket implementation, asset consumers, artifact origin, blast radius, related incidents, build contents, ownership — never unrestricted model-generated graph queries.
Time-travel & recovery
as_of reads, graph diffs, signed-event replay, tombstones, identity review, retention, online backup and isolated recovery drills — history is inspectable and reproducible.
Decision record: ADR-0011 · Governed Production Knowledge Graph & GraphRAG.
6
Diagrams
Reference diagrams
Twelve diagrams, synchronized to the v3.2 architecture. Start with the one-pager, then drill into the layered stack, governed ticket run, deployment shapes, AI operating system, model routing, dual-mode RAG, governed-engine state machine, agent harness, enterprise planes, promoted Core Intelligence and the Canonical Forge Event Spine. The numbered set is available as SVG, PNG and PDF; the Event Spine uses a responsive SVG source. Select any thumbnail to inspect it in the wiki viewer, or open the complete architecture gallery.
7
Deployment
Two ways to run it — one FORGE_PROFILE
Forge deploys in one of two shapes, selected by a single FORGE_PROFILE environment variable resolved by deployment_profile.py, which derives the legacy flags and fails closed on any conflict. Both ship as a repo-free, signed .pyc package — a studio stands Forge up without cloning the repository. See ADR-0002 and the deployment-view diagram.
Local · FORGE_PROFILE=local
One macOS workstation: the launchd-supervised backend on loopback :8787, the browser, a local Ollama pool, JSONL RAG, and the native tools (Unity, Photoshop, Perforce, Git) — all on-device, private, $0. The distribution now ships as separate, digest-verified server and optimized client packages that are joined locally by FORGE_FRONTEND_DIR. No remote worker is required. Local package setup →
Hybrid · control-plane + workers
A control-plane host runs the shared backend with RBAC/SSO, PostgreSQL + pgvector knowledge, and cloud routing — but touches no game tools. Authenticated workstation workers (FORGE_PROFILE=worker) run Unity, Photoshop, Perforce and Git locally and enrol with a single active credential. The control plane holds knowledge and governance; the workers hold the tools.
8
Decision records
Architecture Decision Records
The load-bearing choices are captured as ADRs in docs/architecture, each with context, the decision, and its constraints.
ADR-0001 — RAG deployment modes
Local JSONL vs hybrid PostgreSQL + pgvector; EmbeddingContract, QueryScope, row-level security, fail-closed. Accepted.
ADR-0002 — Distribution & packaging
One FORGE_PROFILE (local / control-plane / worker); repo-free signed backend; control-plane + worker split. Proposed — implemented, pending SRE + security sign-off.
ADR-0003 — Code Intelligence Engine
Structural-first intelligence behind an evidence contract (impacted symbols, call chain, blast radius); Graphify as the first provider — derived evidence, never a gate. Accepted and operational — used by bug fixing, AI Draft, planning, review, validation, Weave architecture/impact answers, root-cause analysis and release-risk analysis. Revision-seeded incremental refresh, telemetry, bounded graph views, versioned evaluations and explicit human feedback improve it without exposing the raw local graph.
ADR-0006 — Fabric Core Intelligence
Reasoning, recovery, agent fabrication and verification promoted behind one typed, default-deny Intelligence Gateway; Core Orchestrator selects at most one qualified specialist; advisory-only, with a Settings kill switch and emergency override. Accepted and promoted to default-on.
ADR-0010 — Collaboration Event Spine
A canonical, server-attested, hash-chained fact bus (forge.event.v1) with idempotent admission; read-only Operation Rooms, RAG, audit and live-UI projections that cannot execute or approve. Accepted for workstation milestone 1.
ADR-0011 — Production Knowledge Graph & GraphRAG
A rebuildable, workspace-scoped read projection that federates Graphify, workflow DAGs and the Event Spine; typed entities with trust classes; bounded typed operations and hybrid GraphRAG; SQLite/FTS5 with a PostgreSQL adapter. Accepted — local projection & hybrid retrieval implemented.