docs: record architecture decisions (ADR-0001..0009) and operations knowledge
CI & Release / Verify simulator (push) Successful in 11s
CI & Release / Trivy scan (push) Successful in 8s
CI & Release / Semantic Release (push) Successful in 5s

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:
2026-07-09 11:41:05 +01:00
parent ea062af86a
commit d3ccd6f94e
19 changed files with 488 additions and 0 deletions
@@ -0,0 +1,38 @@
# ADR-0001: No swarm-wide orchestrator; coordinate through data
## Status
Accepted (2026-07-08)
## Context
The fleet flies fully autonomously with no internet uplink and only
intermittent mesh connectivity between drones. A conventional control plane
(Kubernetes across the swarm, a leader election, a central scheduler) assumes
stable membership and low-latency links — exactly what a swarm does not have.
Partitions are the normal case, not the exception.
## Options
| Option | Pros | Cons |
| --- | --- | --- |
| A — Cluster orchestrator spanning the swarm | Familiar tooling | Assumes stable membership; a partition stalls coordination; single point of failure in the air |
| B — Each drone autonomous, coordinating through exchanged data | Survives partitions; no air-side control plane to fail | No global view; behaviour must be derivable from local state |
## Decision
Every drone is an autonomous node. There is **no orchestrator spanning the
swarm**. Coordination happens by exchanging derived state (see
[ADR-0003](ADR-0003-sync-derived-state-only.md)), and each drone makes its own
in-flight decisions against its local data window. Orchestration tooling
(Kubernetes, Flux) is confined to the **ground** segment
([ADR-0006](ADR-0006-iac-boundaries.md)).
## Consequences
- The platform degrades gracefully under partition: a drone that loses peers
keeps flying and recording.
- There is no single "fleet state" to query in the air; health questions are
answered from each drone's own store and reconciled on the ground.
- Design principle 1 in [`../../README.md`](../../README.md) and the on-board
model in [`../02-architecture.md`](../02-architecture.md) follow from this.