Platform Architecture Overview
Why the architecture is shaped this way
The core bet (see docs/os/synedrix-os-technical-platform-thesis-v0.2.md and docs/os/synedrix-os-core-principles-v0.8.md) is that coordination quality, not model power, is the durable value in a multi-agent system (Principle 2). Models, tools, and individual agents will churn; what must stay stable is how goals decompose into tasks, how agents are bounded, how governance gates execution, and how everything remains observable and auditable. Every layer, contract, and invariant in this repo exists to protect that bet.
The 12 core principles
Defined canonically in docs/os/synedrix-os-core-principles-v0.8.md (numbering is fixed and cited by name+number elsewhere, e.g. “Principle 4”):
| Cluster | Principles | Concern |
|---|---|---|
| Safety | 1 Bounded autonomy, 4 Governance before execution, 5 Shared context with scoped access | Keeping an agent inside its lane |
| Architecture | 2 Orchestration is the center of gravity, 3 Specialised agents over mega-agents, 12 Deterministic idempotency, explicit state | Keeping the system maintainable as it grows |
| Human control | 6 Humans stay above the automation layer, 8 Event-driven execution | Where human authority sits and how the system stays responsive |
| Accountability | 7 Explainability and audit by design | How the system explains itself |
| Platform | 9 One substrate, many domains, 10 Trust is the real product, 11 Open by default, sovereign by design | The substrate everything runs on, and the point of it |
The 12 canonical layers
Full definitions: docs/os/synedrix-os-layer-taxonomy-table-v0.8.md. The authoritative layer list, including must_not_own boundaries and the slice topology, is canonical/architecture.yaml (meta.layer_count: 12).
| # | Layer | Owns | Platform mapping |
|---|---|---|---|
| 1 | Human Interface | Dashboards, approval surfaces, command UIs | — |
| 2 | Goal & Intent | Goal schema, playbooks, KPI targets | — |
| 3 | Orchestration | Workflow router, task graph, retries, escalation | n8n |
| 4 | Agent Runtime | Agent lifecycle, execution state, stateful/cyclic reasoning | LangGraph (+ LangChain) |
| 5 | Agent Registry | Agent metadata, permissions, lifecycle status | — |
| 6 | Tool Abstraction | Adapters, tool contracts, permission scopes | — |
| 7 | Memory & Data | Transactional/hot/temporal/graph/vector stores; memory control plane (tier taxonomy, record lifecycle, recall mediation, promotion, decay and erasure) | Supabase PG17, Redis, QuestDB, Neo4j, Qdrant |
| 8 | Event | Event envelope, routing, correlation IDs | Hookdeck, Hookdeck Outpost |
| 9 | Governance & Controls | Policy rules, approvals, audit controls | — |
| 10 | Observability | Logs, traces, metrics, decision lineage | Langfuse, PostHog, Grafana LGTM |
| 11 | Domain Pack | Domain entities, agents, workflows, policies | Trading, Art, Commerce, Finance, Ops, Mini Reachy Dev Assistant, Engineering (see ADR-027 and Domain Packs) |
| 12 | Business Instance | Tenant config, credentials, thresholds, deployment_mode, domain_pack_version pin, Capability Module entitlement flags, BIE version | — |
The five canonical layer principles from canonical/architecture.yaml govern every layer boundary decision:
- Shared before specific — if a concern can be reused across domains, it belongs in a shared OS layer, not a domain pack.
- Controls before execution — execution paths must pass through governance and observability instead of bypassing them.
- Tools are adapters, not business logic — external systems are accessed through normalized adapters.
- Memory is shared, access is scoped — agents share context but memory access is selective and policy-aware.
- Memory moves only under governance — a record crosses a memory tier, is recalled, or is erased only through a governed path.
Four-plane projection
ADR-OS-015 admits a four-plane view of the OS agent set (Orchestration, Control, Intelligence, Memory) as a presentation grouping over family and layer, not as a layer change or a taxonomy. The layer count stays twelve and no agent’s classification changes; the projection simply draws agents into planes based on how their families and layers relate to organisational roles.
A domain pack owns everything its capability needs that is not a shared OS primitive — including, for any domain pack, session transport, the speech pipeline, and the embodied endpoint bridge if the domain pack includes voice or robotics concerns. These are domain pack concerns at Layers 11/12, not OS-owned layers (see Domain Packs).
OS vs. domain pack vs. business instance
Defined in docs/os/synedrix-os-taxonomy-spec-v1.0.md and enforced by docs/os/synedrix-os-responsibility-matrix-v0.7.md:
- Synedrix OS — the reusable substrate: orchestration, agent lifecycle, memory primitives, governance, tool mediation, observability. Must never contain domain-specific logic, entities, or policies.
- Domain pack — a modular business capability package (Trading, Art, Commerce, Finance, Ops, Mini Reachy Dev Assistant, Engineering) that contributes domain entities, agents, workflows, event catalogs, policies, and KPIs on top of the OS. All domain packs are peers — none is privileged. Domain packs can also offer Capability Modules: reusable, independently versioned, licensable sub-packages that business instances enable via explicit entitlement flags (see ADR-OS-005).
- Business instance — a concrete deployed runtime: OS + one or more domain packs + tenant configuration (secrets, credentials, thresholds, approver roles, deployment mode). A business instance may also register a Business Instance Extension (BIE) — a customer-specific, non-reusable customization layer governed through the same agent registry schema and Policy Guard — and may enable specific Capability Module entitlements. Never shares OS-owned abstractions or stores domain secrets.
Deployment modes (summary)
Three canonical deployment modes (cloud-connected, self-hosted-hybrid, air-gapped) govern where model inference happens and whether external API calls are permitted — every other behavior of the platform is identical across modes. The authoritative specification is docs/os/synedrix-os-deployment-model-spec-v0.4.md, which also corrects the Hookdeck open-source inventory row (Hookdeck inbound gateway is proprietary and not self-hostable; Hookdeck Outpost is open source and self-hostable). Full detail lives in Operations → Tech Stack & Deployment, because deployment mode is fundamentally an infrastructure/tech-stack concern.
Per the tenancy model (ADR-OS-008), the platform is split into a pooled control plane and a per-tenant data plane. A data plane is never pooled across tenants. The self-operated variant runs on the customer’s own infrastructure and is available in all three modes; the managed variant is operated by Synedrix on the customer’s behalf (dedicated to one tenant) and is available in Modes 1 and 2 only. Mode 3 is self-operated only — a managed data plane would give a third party operational access to an environment whose definition forbids third-party handling beyond the single inbound Hookdeck path. An air-gapped business instance cannot declare cloud model URIs in any agent runtime policy — this is a validation invariant enforced by the OS.
Governed execution invariants (ADR-028)
ADR-028 adopts five execution invariants that apply to every agent invocation — OS agents, domain-pack agents, n8n workflow agents, and delegated tool calls. They are independent obligations, not aspirations:
- Explicit purpose — every invocation has a tenant-scoped, versioned task or goal reference, a task objective, an originating principal, constraints, and a declared outcome contract. The orchestrator must not silently invent acceptance criteria.
- Delegated authority — effective permissions are bounded by the intersection of registry permissions, principal delegable scope, runtime policy, business-instance restrictions, deployment rules, tool scope, and approvals. A denial at a guarded tool boundary is final for that action; the run may continue with a compliant alternative per ADR-018, but the invocation ends
blockedwhen no compliant path remains. - Traceable evidence — the system maintains reconstructable lineage linking intent, plan, actor, delegation, policy decision, human approval, tool intent/effect, and terminal outcome. Correlation IDs are not idempotency keys; audit records must be append-only or tamper-evident.
- Honest uncertainty — agent outcomes must distinguish observed facts, inferred conclusions, assumptions, and unresolved unknowns. Material unresolved uncertainty blocks claims of successful business completion; unknown external effects require reconciliation before any non-idempotent retry.
- Conditional completion — the system distinguishes invocation termination, side-effect confirmation, and business-goal satisfaction. Authoritative business completion is determined by a governed acceptance evaluation against a versioned contract; an agent’s proposal that work is complete does not itself constitute completion.
These invariants apply at the following layer boundaries: L2 defines the goal contract, L3 coordinates delegation and settlement, L4 executes reasoning within the constraints, L5 resolves eligibility, L6 mediates external effects, L7 stores audit provenance, L9 enforces policy, L10 correlates evidence, L11 supplies domain acceptance criteria, and L12 configures instance-specific restrictions. A governed remediation lifecycle (detect → diagnose → plan → authorize → execute → verify → settle) extends these invariants to corrective actions without erasing original immutable evidence.
Engineering domain pack (ADR-027)
ADR-027 places Synedrix’s own engineering agents — the team that designs, judges, builds, and maintains Synedrix OS and its domain packs — in a new Engineering domain pack with layer code eng / ENG at Layer 11, not as os-agt-* entries in the core OS agent registry.
The eng pack’s role set includes: an Engineering Architect (canonical authority on the OS canon), a Steward (conventions), a Builder (OS canon and reference stack), a Publication Gatekeeper, a Domain Manager, and a Domain Builder — each with distinct authority profiles. Workers (subagents) hold strict subsets of their parent’s tools, are not registered separately, and are traced under the parent’s agent_id. All roles entered through the lab lane first (LAB-003) before any registry promotion. General agent sessions (Claude Code, Codex, Cursor, etc.) are unregistered developer tooling; the Deep Agents deployment enters the lab lane, and only upon promotion do agents receive eng-ctl-* / eng-exe-* identifiers and full governance bridge connectivity through n8n, Policy Guard, and the HITL Gateway.
See Domain Packs for the complete list of packs and their registration process.