eSlider
d3ccd6f94e
Add docs/adr/ with a chronological ADR set reconstructed from the project history (no orchestrator, one storage format, derived-state sync, SQL-over-SSH contract, WireGuard beneath SSH, IaC boundaries, non-root image, runtime data paths, bounded lake scans), an index README, and a template. Distinguish repo-local ADRs from ecosystem-wide ASRs. Expand AGENTS.md with a decision-records section and a runtime/operations guide (service URLs, rebuild workflow, CPU budget knobs). Reference the ADRs from README, CONTRIBUTING, and the affected design docs, and add an open question for T1 partition pruning.
Architecture Decision Records
This directory records the significant decisions behind Swarm House, in the order they were made. Each record is immutable once Accepted — a later decision that changes course gets a new number and supersedes the old one rather than editing it.
ADR vs ASR
| Kind | What it captures | Where it lives |
|---|---|---|
| ADR (Architecture Decision Record) | A point-in-time decision for this repository, with the options considered and their consequences | Here, in docs/adr/ |
| ASR (Architecture Standard Record) | A standing, cross-repository policy every project must obey (Go-first, secrets, layout) | The ecosystem inventar repo, not here |
The rules in ../../AGENTS.md are this repo's local standing
constraints; anything ecosystem-wide belongs in inventar as an ASR. Design
decisions specific to the platform are ADRs and belong here.
Index
| ADR | Decision | Status |
|---|---|---|
| ADR-0001 | No swarm-wide orchestrator; coordinate through data | Accepted |
| ADR-0002 | One storage format on every tier — Parquet + DuckDB, Hive layout | Accepted |
| ADR-0003 | Sync derived state only; raw telemetry stays local | Accepted |
| ADR-0004 | Read-only SQL-over-SSH as the peer query contract; no debug API | Accepted |
| ADR-0005 | WireGuard beneath SSH for the mesh transport | Accepted |
| ADR-0006 | IaC split: Ansible hosts, Terraform ground, Flux ground-only, fleet manifest for drones | Accepted |
| ADR-0007 | Run the simulator image as a non-root user | Accepted |
| ADR-0008 | Shared var/t1 / var/t3 runtime paths; state out of Git |
Accepted |
| ADR-0009 | Bound observability lake scans to a flight window and cache | Accepted |
Writing a new ADR
- Copy
TEMPLATE.mdtoADR-NNNN-short-slug.md(next free number). - Fill in Context, Options (if more than one was real), Decision, Consequences.
- Add a row to the index above.
- Cross-link the ADR from the design doc it affects (and vice versa).
Keep the tone laconic: state the decision and why, skip the narrative.