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.
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# ADR-0003: Sync derived state only; raw telemetry stays local
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (2026-07-08)
|
||||
|
||||
## Context
|
||||
|
||||
Each drone produces high-rate sensor telemetry and on-board video detections —
|
||||
far more than the mesh can carry. But peers only need enough to coordinate
|
||||
flight: where everyone is, where they are heading, what was detected. Pushing
|
||||
raw feeds across the air would saturate the radio and drain batteries for data
|
||||
nobody reads in flight.
|
||||
|
||||
## Decision
|
||||
|
||||
Only **derived state** crosses the air — position, attitude, detections — as
|
||||
small pub/sub broadcasts (~5 Hz). **Raw telemetry stays on local NVMe** until
|
||||
the drone lands, then travels to the warehouse during offload
|
||||
([ADR-0002](ADR-0002-one-storage-format.md)). The design is **event-driven**:
|
||||
new derived data triggers downstream action through hooks; nothing polls asking
|
||||
"anything new yet?".
|
||||
|
||||
## Consequences
|
||||
|
||||
- Air bandwidth scales with the number of peers and the broadcast rate, not
|
||||
with sensor resolution.
|
||||
- The warehouse is the only place with the full picture; in-flight decisions use
|
||||
the local window plus peer broadcasts.
|
||||
- Broadcast staleness per peer becomes a first-class health signal
|
||||
([`../07-observability.md`](../07-observability.md)).
|
||||
- What syncs and what does not is specified in
|
||||
[`../04-swarm-sync.md`](../04-swarm-sync.md).
|
||||
Reference in New Issue
Block a user