System Design
System Design documents how Spectral is built — the decision-time mechanism, the three-context architecture, and the technical decisions that shape the codebase. Where How Spectral Works introduces what Spectral does and why the two-pillar shape works, this section is the authoritative technical reference for engineers working in the system.
The diagram below is the visual TOC: each box is a load-bearing primitive that the rest of
System Design builds on; each subgraph names a context (spectral.platform, spectral.worlds,
spectral.core) and the caller surface that drives a decision.
A caller (the customer’s agent) invokes POST /decide with (org_id, domain, action, context). The decision-server routes to the deployed
action module for (org, domain, action, world_model_version), loading from the content-addressed
module store on first request and caching it thereafter. The composition root validates supplied context against the embedded
context schema, runs derivations for computed attributes, evaluates each rule’s
applies_when filter and main predicate in severity order, applies suppression chains, and runs the action’s aggregation mode. The response is a binding
{ status, work_frame, decision_metadata } per ADR-077 D3; every decision is written to the audit chain
per ADR-076 D3, which backs the deployment-scoped System Card.
The world-model system produces the action modules the platform runs. Operators author rules in natural language; the World Agent generates the predicate code; two gates (implementation-readiness + conformity) guard draft-to-catalog acceptance; published versions write action modules to the module store with content hash, code provenance, and signature per ADR-080.
For per-primitive detail — definitions, structure, lifecycle, the relationships that constrain each one — see the Primitives reference.
How the rest of System Design is organized
Section titled “How the rest of System Design is organized”System Design is structured as six groupings. Read top-to-bottom for a guided walk, or jump to whichever answers your current question.
- Foundations — Architecture (single-library, three-context, Clean-Architecture-per-context), Decision Execution (the five-phase breakdown of every
/decideinvocation), Contract Surfaces (the categorical inter-context surfaces, including events as substrate transport), Access Control, Security Boundaries, Data Retention, Observability Principles. - Agents — Agent Architecture, the memory model (Memory System + Agent Memory Primitives), Tool Invocation, Chat Privacy, plus the harness substrate that supports agent reasoning (Embeddings, the LLM Platform).
- World Model System — the executable authoring authority: World Model (context schema, configuration, action registry), rule architecture, evolution loop with both gates, World Model Card.
- Platform — the decision host: decision API + MCP surface, decision-server, module store, audit chain, Customer Dashboard, Explainability, customer Notifications, and the customer control plane.
- Operations — the operator’s cross-context staff surface: world-model authoring, source-material distillation, version publication, release notes. Operates on both worlds-context and platform-context concerns.
- Topology — Frontend Architecture and the Infrastructure substrate (hosting, deployment topology, CD pipeline).
Two control planes live inside their respective subsystems: customer-side under Platform, operator-side as the Operations top-level grouping. Symmetric architecture, asymmetric placement — the operator’s surface spans contexts, so it doesn’t nest into one.
What’s next
Section titled “What’s next”- Architecture — the three-context layout that holds the primitives above.
- Decision Execution — the five phases every
/decideinvocation flows through. - World Model System — how the authoring authority produces deterministic decision modules.