Decision records¶
Why the system is built the way it is. Each record states the problem, the decision, and what it cost — the reasoning behind a choice, not instructions for using it. For how to run Orpheus see the Operator's Manual; for how to change it, Coding & Contributing. Proposals that are not yet decisions live in design docs.
Status means: live — this describes the system now. Superseded — a later record replaced part or all of it; the record stays, because the reasoning is still worth reading. Partially implemented — the decision is made and some of it has shipped.
| # | Title | Status |
|---|---|---|
| 0001 | Documentation and instruction consolidation | Superseded — AGENTS.md replaced CODING_AGENT_CONTEXT.md; themed files replaced the single-document model |
| 0002 | Video snapshot architecture | Live |
| 0003 | Timelapse generation architecture | Superseded in part by 0007 — the scheduling section is dead; tiers, filenames and bucket sampling are live |
| 0004 | Jetson video codec strategy | Live |
| 0005 | Event-driven architecture with JSON sidecars | Superseded in part by 0006 — the InferenceEvent layer is now an alias; sidecars and migration are live |
| 0006 | Event hierarchy and taxonomy | Live |
| 0007 | Timelapse scheduling and required labels | Live — supersedes part of 0003 |
| 0008 | Shared Makefile includes | Live |
| 0009 | uv for Python version management | Live |
| 0010 | BirdNET multi-label and soft geo-admit | Live — structurally a validation report rather than a decision record |
| 0011 | Temporal localisation and taxonomy references | Live |
| 0012 | Agents own their detection stream | Live |
| 0013 | Source-identity entities | Live — what entity merge keys on, and what it deliberately does not |
| 0014 | Independent component versioning | Live |
| 0015 | EventBus abstraction over the transport | Superseded in part by 0017 — the ABC and factory are live; its "mqtt" default is not |
| 0016 | Entity-type state-space taxonomy | Live |
| 0017 | Hand-rolled actors on a NATS + JetStream backplane | Live — supersedes 0015's transport posture |
| 0018 | Distributed backplane and config service | Partially implemented — the config backends, KV layer and orpheus-config-push shipped; install profiles and cert lifecycle have not |
Records are immutable once accepted: a decision that changes gets a new record
and a Superseded line on the old one, rather than an edit.