Technical architecture overview

This page is the documentation map: how components are arranged, how a request crosses the system, then where to drill into layering, the kernel lifecycle, and governance. It does not replace topic pages; it is one navigable overview.

Deployment topology (typical private install)

flowchart LR
  B[Browser / SDK] --> W[Console or gateway]
  W -->|REST / SSE| R[runtime]
  R --> PG[(Postgres or SQLite)]
  R --> Obj[(MinIO / S3)]
  R --> LLM[Model provider]

The console talks to the runtime over HTTP/SSE. The business database and object store stay close to the deployment. Multi-instance setups must use object storage for the file sandbox, not local disk alone. See File sandbox and Deployment verification.

Five logical layers

flowchart TB
  subgraph Client["Client"]
    SDK["SDK / HTTP"]
    Web["Web console"]
  end
  subgraph Access["Access"]
    HTTP["HTTP / SSE"]
    Auth["Auth / identity binding"]
    Ctx["RequestContext"]
    EE["Enterprise license gate"]
  end
  subgraph Service["Service"]
    API["API routes"]
    Plug["Plugins / events / govern"]
  end
  subgraph Engine["Runtime engine"]
    Sess["Session orchestration"]
    Tool["Tools"]
    Prov["Model gateway"]
    Hitl["HITL / breaker"]
    Fs["File sandbox"]
  end
  subgraph Data["Data"]
    Store["SQLite / Postgres"]
    RLS["RLS / audit / observation"]
  end
  Client --> Access --> Service --> Engine --> Data
  Prov --> ExtLLM[Model provider]
  Fs --> ExtS3[Object storage]

Layer	Responsibility
Client	Call REST/SSE with isolation and role context
Access	Protocol termination, identity binding, three-dimensional context, RBAC, license gate
Service	External contracts, plugins, events, cross-process /govern
Runtime	Session loop, tools, models, sandbox, approval and breaker hooks
Data	Persistence, migrations, row-level security, audit and observation

Layer details: Layered architecture.

Request path

sequenceDiagram
  participant C as Client
  participant A as Access
  participant S as Service routes
  participant E as Runtime
  participant D as Data
  participant Bus as SSE

  C->>Bus: Subscribe /event (optional, recommended)
  C->>A: POST session / trigger / …
  A->>A: Identity · tenant · RBAC · license
  A->>S: Route
  S->>E: SessionPrompt / dispatch / governance
  E->>D: Message / Part / audit / …
  E-->>Bus: Deltas and status
  Bus-->>C: Event stream
  E-->>C: Sync response (if using a sync API)

How one prompt becomes a tool call: End-to-end request lifecycle and HTTP streaming and SSE. How triggers fire: Trigger component chain.

Where governance attaches

Governance is not embedded inside a single agent binary. It hangs on a deployable service surface:

Attachment	Role	Topic
Access RBAC / identity	Who may call which APIs	RBAC · Identity
Tool permission / HITL	Whether an action runs; whether another person must approve	HITL
Breaker	Global stop	Breaker
Audit chain	Whether history can be re-hashed after write	Hash-chain audit
/govern	Cross-process pre-check	Out-of-process governance
Data RLS	Tenant row isolation	Multi-tenant RLS

Load boundary between MIT core and enterprise code: Open-core seam.

Storage and isolation (quick reference)

Item	Notes
Engine	SQLite by default; Postgres when a connection string is set
Isolation	Postgres: app.tenant_id + RLS; production roles must be NOBYPASSRLS
Dimensions	tenant / owner / model enter request context
Sandbox	local or minio/s3; multi-instance forbids local
Audit / observation	Streams are queryable; integrity verify is license-gated

Config chain from capability to run

flowchart LR
  Cap[Skill / MCP] --> Role[Agent Role]
  Role --> Trig[Trigger]
  Trig --> Run[Session or TeamRun]

See Three abstractions and Team collaboration.

Drill-down

Question	Go to
Per-layer detail	Layered architecture
Why out-of-process	why-cs
How one chat turn runs	Kernel lifecycle
Reliability and deploy	Reliability
Selection claims	Why Agent Forge

---

Related:

• Layered architecture: client to data
• End-to-end request lifecycle
• Architecture hub