Architecture
The Architecture room is the reference map of how the system is built. It describes each subsystem, links every decision to its ADR, and defines the shared vocabulary once — in Concepts — so nothing is defined twice.
Read Concepts first. Then follow the subsystem links. When you want the reasoning behind a decision, follow the ADR link on the subsystem page.
The spine-first philosophy
The Reality Kernel is built spine-first, domain-agnostic from day one (ADR-0001, ADR-0015). No engine inside the kernel branches on a domain type. Domain content lives in realms/ and is registered into the kernel at boot — the contribution boundary is the invariant that makes multi-domain operation possible without private reality.
The build is sequenced: Slice 1 proves the write→event→projection→read spine on a concrete domain. Slice 2 introduces the realm compiler and proves that adding a second domain is a relocation of definitions, not a re-architecture of engines (ADR-0014).
Subsystem map
Core model
| Subsystem | What it is | Status |
|---|---|---|
| Reality Kernel | The horizontal operational kernel: spine, contribution boundary, the “one kernel, no private reality” doctrine | ✅ Decided |
| Data Model | How reality is represented: Entities/Objects, Traits/Attributes, Statements, and Value Types | ✅ Decided |
| Concepts | The canonical glossary — every core term defined once; all other pages link here | ✅ Reference |
Versioning and truth
| Subsystem | What it is | Status |
|---|---|---|
| Branches and Scenarios | Definition-layer branching (decided) and operational-state overlays (deferred) | ✅ Branch decided / ⏸ Scenario deferred |
| Consistency | Source-of-truth model: synchronous current-state + async secondary projections (hypothesis under spike) | 🟡 In progress |
| Realms | Lightweight namespaces — domain partitions, integration sources, environment tiers | ✅ Decided |
Operation and integration
| Subsystem | What it is | Status |
|---|---|---|
| Writeback | Intent-first writeback to external systems: model the saga, stub the dispatch | ✅ Decided |
| Topology | Adjacency CTEs + precomputed blast-radius projection behind an interface | ✅ Decided |
| Agent Runtime | Code-mode over the generated typed SDK; authority enforced per SDK call | ✅ Decided |
| Offline | Offline-ready by kernel design; online-first in the proof build | ✅ Decided |
| Legacy Connector | SmartInventory coexists as an external connector; no big-bang migration | ✅ Decided |
Boundaries and build
| Subsystem | What it is | Status |
|---|---|---|
| Kernel Language | TypeScript-default vs Java — gated on a one-week build-off | 🟡 In progress |
| Delivery Sequencing | Serial delivery for a 2–3 person team; spine first, then breadth | ✅ Decided |
How to read this section
- Concepts first. Every term used in the subsystem pages is defined in Concepts. If a word is unfamiliar, look it up there before reading the subsystem page.
- Subsystem pages describe what is built and decided. They do not re-argue decisions. For the reasoning, follow the ADR link at the top of each page.
- ADRs for the why. The full decision record — context, alternatives considered, consequences — lives in Decisions (ADRs). The index there is the authoritative status table.
- Two ADRs are still Proposed. Consistency and Kernel Language are gated on spikes that have not yet run. Do not treat their hypotheses as decided facts — the pages say so explicitly.