Architecture
This section is the platform's decision record: what was decided, what is currently proposed, and the carefully-scripted procedures for enabling safety-critical changes.
In plain English: software teams write down big design decisions in short numbered documents called ADRs (architecture decision records) so that, years later, anyone can answer "why is it built this way?" without archaeology. Reading an ADR's Context and Decision sections is usually enough; the Consequences section tells you what trade-offs were accepted.
Current program: the first-class module transformation
The active architecture program (ADRs 033–039, Phase 1 landed August
2026) promotes the alphaswarm Python namespace into a stable public
domain/application kernel behind a compatibility facade:
- Transformation plan — the staged program.
- Evidence index — proof obligations and their status.
- Legacy domain import inventory — what still imports the old paths.
- Key ADRs: 033 canonical module, 034 activity & simulation boundaries, 035 engine selection & registry, 036 control/data/money plane boundaries, 037 research-to-order authorization, 038 legacy compatibility & deprecation, 039 Nautilus optional adapter boundary.
What lives here
| Kind | What it is | Examples |
|---|---|---|
| ADRs | Numbered, immutable decision records (superseded rather than edited) | 001 static export over SSR → 039 Nautilus adapter boundary |
| RFCs | Proposals under discussion | Forecast/scenario domain types |
| Plans & analyses | Multi-ADR programs and platform analyses | Transformation plan, Minimum AWS coverage |
| Safety runbooks | Scripted enablement of dangerous flags | Halt propagation staging enablement, Tenancy RLS enforcement enablement |
| Specifications | Detailed subsystem specs | Preprocessing spec |
| Guides | How to extend the architecture | Enhancement guide |
Reading order for newcomers
- Concepts → Architecture — the system map (this section assumes you've seen it).
- ADRs 005 separated control plane, 029 catalog-first data object model, 032 graph data pillar, and 036 plane boundaries — the four decisions that most shape everything else.
- The current program above.