docs: record architecture decisions (ADR-0001..0009) and operations knowledge

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.
2026-07-09 11:41:05 +01:00
parent ea062af86a
commit d3ccd6f94e
19 changed files with 488 additions and 0 deletions
@@ -29,3 +29,52 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and TDD re
 - TypeScript: strict mode, functional components and hooks, no extra UI libraries.
 - YAML: 2-space indent.
 - Diagrams: Mermaid inside Markdown.
+
+## Decision records
+
+Significant architectural decisions are recorded chronologically as **ADRs** in
+[`docs/adr/`](docs/adr/) — one immutable file per decision, in the
+Status / Context / Options / Decision / Consequences format. Start from
+[`docs/adr/README.md`](docs/adr/README.md).
+
+- **ADR** = a point-in-time decision for *this* repo → `docs/adr/`.
+- **ASR** = a standing, ecosystem-wide standard (Go-first, secrets, layout) →
+  lives in the `inventar` repo, **not** here.
+
+When a change alters a boundary, contract, or trade-off, add an ADR (copy
+[`docs/adr/TEMPLATE.md`](docs/adr/TEMPLATE.md), take the next number, update the
+index) and cross-link it from the affected design doc. A later reversal gets a
+new ADR that supersedes the old one — never edit an Accepted record.
+
+## Runtime & operations (sim environment)
+
+The k3d ground miniature is `swarm-sim`. Services are exposed as NodePorts:
+
+| Service | URL |
+| --- | --- |
+| Explorer (T1 live lake) | `http://localhost:30088` |
+| Warehouse explorer (T3) | `http://localhost:30089` |
+| Grafana (dashboards `swarm-fleet`, `swarm-platform`) | `http://localhost:30300` |
+| Prometheus | `http://localhost:30990` |
+| MinIO console | `http://localhost:30901` |
+| Prototype dev server (`npm run dev`) | `http://localhost:5173` |
+
+Rebuild the simulator image and roll it out:
+
+```bash
+cd simulator && docker build -t swarm-house/simulator:dev .
+k3d image import swarm-house/simulator:dev -c swarm-sim
+kubectl rollout restart -n swarm statefulset/drone deployment/explorer deployment/exporter
+cd infra/terraform/sim-env && terraform apply
+```
+
+**CPU budget knobs** (see [ADR-0009](docs/adr/ADR-0009-bounded-lake-scans.md)):
+`METRIC_FLIGHT_WINDOW` (scan only recent flights), `SCAN_INTERVAL_S`,
+`VIEW_REFRESH_S`, `TREE_CACHE_S`, `KEEP_ALIVE=1` (drones idle after seal instead
+of restarting), `IMU_HZ`. Never scan the full lake on a hot path — it grows with
+pod churn. Long-horizon analysis is a T3 warehouse query, not an exporter job.
+
+Runtime data lives under `var/t1` / `var/t3`, owned by uid **10001**
+([ADR-0007](docs/adr/ADR-0007-non-root-image.md),
+[ADR-0008](docs/adr/ADR-0008-runtime-data-paths.md)); both are gitignored.
+Terraform state is local and never committed.