Architecture Overview
Understand SOIT as a governed runtime with a stable kernel, domain modules, adapters, and workspace UI.
SOIT follows a hexagonal architecture. A stable kernel defines runtime semantics, contracts, specs, security, events, identity, registry, and ports. Domain modules implement product behavior on top of it. Adapters connect replaceable external systems. The API layer exposes transport surfaces, and the web app provides workspace and admin routes.
Layers
| Layer | Responsibility |
|---|---|
Web (web/) | Workspace UI, routes, state, API clients, shared components — no backend business rules |
API (app/api) | REST, WebSocket, SSE transport, request parsing, response envelopes — kept thin |
Modules (app/modules) | Product domains: agent, workflow, knowledge, modelhub, plugin, observe, evaluation, memory, notification, identity, secrets, security, versioning |
Kernel (app/kernel) | Stable core: contracts, specs, runtime, identity, security, registry, events, trace, and ports |
Adapters (app/adapters) | Port implementations for LLM, tools, vector, storage, secrets, and plugins — no business logic |
| Infrastructure | PostgreSQL, Redis, Milvus, MinIO, Vault, Celery workers |
The core execution path
Every user action — a chat turn, a task, a workflow run, a knowledge operation — flows through the same governed path:
- The web workspace calls the API over REST, WebSocket, or SSE.
- The API layer orchestrates the request into a domain module.
- The module uses kernel specs, registry, runtime, security, and ports.
- The kernel writes runs, tasks, run steps, and trace state to PostgreSQL, and records pending events in the outbox — in the same transaction.
- The dispatcher reliably hands events to Celery workers.
- Workers execute side effects through governed adapters, which call models, tools, vector search, object storage, or secret services.
- Results, costs, latency, and errors flow back into the runtime ledger; the API returns synchronous results or streams events to the UI.
Nothing reaches an external system except through a governed adapter, and nothing executes without leaving trace evidence.
Design principles
- Spec-first — agents, workflows, tools, knowledge, and plugins are constrained by versioned JSON Schema specs and contracts.
- Scope-by-default — API, modules, and the data layer are organized around tenant/workspace scoping.
- Trace-everything — execution lands uniformly in Run, Task, RunStep, and Trace records.
- Gateway-only — LLM, tool, vector, storage, and secret access goes through ports and adapters; business code never calls provider SDKs or raw HTTP directly.
- Immutable-versions — versions are append-only; release pointers express what is live. See Versioning and Release.
Capability governance
Capabilities from any source — built-in tools, plugins, MCP servers, model providers, knowledge bases, workflows — enter an agent through the same shape: a typed binding carrying capability id, source kind, and version. Governance policy (allowlists, egress rules, RBAC) and Vault-backed workspace secrets apply at the binding level. Bindings resolve into immutable versions, release pointers select what runs in production, and the audit trail records who used which version.
Deployment topology
A running SOIT installation consists of the web app, the FastAPI API, Celery workers, and the runtime infrastructure: PostgreSQL (business data, run ledger, outbox), Redis (broker and cache), Milvus (vector collections), MinIO (documents and artifacts), and Vault (workspace secrets). Workers are the only components that talk to external LLM providers, MCP servers, and enterprise systems — through governed adapters. See Deployment.
Where to go deeper
- Backend Boundaries — the enforced dependency rules.
- Frontend Structure — workspace and admin route organization.
- Data Model — the kernel table families.
- Runtime Ledger — Run / Step / Artifact / Cost semantics.