System Design

System Design documents how Spectral is built — the core primitives, 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 primitive that the rest of System Design builds on; each subgraph names a context (spectral.platform and spectral.worlds) plus the customer-side trace surface that feeds the system.

A customer’s Workspace holds one or more Workspace Agents, each defined by a structured prompt template and hyperparameters. OTEL traces from the customer’s running system become Samples, which compose into a versioned Sample Set. A Change Set bundles proposed mutations to the Workspace Agents and is evaluated against the Sample Set under the workspace’s Evaluation Framework. The framework itself derives from a World Model — Spectral-managed domain authority — which produces a versioned EvalSet consumed by the platform’s optimization pipeline (see Optimization Engine). Optimization tracks genuine domain conformance, not a self-referential rubric.

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

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), Contract Surfaces (the three 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 — domain standards, rule architecture, eval generation, evolution loop, system cards. The worlds-context pillar.
• Platform — the platform-context pillar: Optimization Engine, Explainability, customer Notifications, and the customer Control Plane (dashboard + Spectral Agent).
• Operations — the operator’s cross-context staff surface: Operations Agent, 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

• Architecture — the three-context layout that holds the primitives above.
• Optimization Engine — the pipeline that turns Samples into Change Sets via Evaluation Frameworks.
• Memory System — how agents compound reasoning across runs.