autopilot/_docs/02_document/FINAL_report.md

# autopilot — Documentation Index

**Status**: forward-looking design (Rust). The implementation is in flight. This page is the entry point into the doc set; it does not duplicate content.

If you are new to autopilot, read in this order: `architecture.md` → `system-flows.md` → the component spec(s) you care about → `data_model.md` for entity-level detail → `decision-rationale.md` for *why* the design looks the way it does.

---

## 1. Doc set at a glance

| File | Purpose |
|---|---|
| `architecture.md` | The system. System context, component layering, NFRs, detailed design (problem, restrictions, AC, training data, solution architecture, MAVLink and piloting, MapObjects/H3, MGRS sync, target relocation, MapObjects sync with central DB, tech stack), open questions, scope boundary. |
| `system-flows.md` | Per-flow narratives + sequence diagrams. Frame pipeline, movement detection (zoom-out + zoom-in), VLM confirmation, scan-controller behaviour tree, operator round trip, mission lifecycle, MapObjects + ignored items, MapObjects sync, pre-flight BIT, lost-link failsafe ladder. |
| `data_model.md` | Canonical entity catalogue. Frames, detections, POIs, VlmAssessment, MapObject + observation log + bundle, IgnoredItem, OperatorCommand envelope, MissionItem vs MissionWaypoint, MGRS wire format, persistence + versioning. |
| `decision-rationale.md` | Load-bearing research and decision evidence (per-dimension reasoning chain, fact cards, fit matrix, validation log, source registry, weak-point→fix table, historical seed narrative). |
| `glossary.md` | Project-specific terms. |
| `components/<name>/description.md` | One per autopilot component (13 total): purpose, inputs, outputs, responsibilities, state, failure modes, dependencies, NFR targets, references. |
| `deployment/containerization.md` | Single-binary deployment options (native systemd vs container), target hardware, configuration surface, health endpoint. |
| `deployment/ci_cd_pipeline.md` | Build, test, SITL conformance, benchmark gate, sign + publish. |
| `deployment/observability.md` | Logs (`tracing` + JSON), metrics, traces, health aggregation, replay-driven debugging. |
| `FINAL_report.md` | This file. |

---

## 2. The system in two minutes

`autopilot` is the onboard mission executor for a reconnaissance winged UAV. It runs as a single Rust process on an aarch64 Jetson Orin Nano. It pulls a mission from the external `missions` API (and the mission area's last-known MapObjects state), controls the UAV through a hand-rolled MAVLink layer, drives a ViewPro A40 gimbal in a two-level scan-and-zoom loop (zoom-out wide sweep + zoom-in on POI), streams camera frames + telemetry continuously over modem to an external Ground Station so the operator watches in a browser, and uses bi-directional gRPC to delegate primitive object detection to the external `../detections` API. Movement detection runs at both zoom levels with mandatory ego-motion compensation. Semantic-vision reasoning (Tier 2 + an optional local VLM), a POI scheduler with a ≤5 POIs/min operator-review cap, and a target-follow mode after operator confirmation all run inside autopilot. Pre-flight self-test gates takeoff; the mission's full pass diff is pushed back to the central MapObjects store at mission end. Operator commands are authenticated, signed, and replay-protected.

Full synopsis: `architecture.md §Synopsis`.

---

## 3. Components

The system is 13 components organised into 4 planes:

| Plane | Components |
|---|---|
| Perception (data plane in) | `frame_ingest`, `detection_client`, `movement_detector`, `semantic_analyzer`, `vlm_client` (optional) |
| Decision + Memory | `scan_controller`, `mapobjects_store` |
| Action (data plane out) | `gimbal_controller`, `operator_bridge`, `mission_executor`, `mavlink_layer`, `mission_client` |
| Telemetry plane (always-on, parallel) | `telemetry_stream` |

Per-component design specs: `components/<name>/description.md`.

---

## 4. Architectural non-negotiables

These are stated once in `architecture.md §5` and referenced everywhere:

- Detection-as-a-service (Tier 1 lives in `../detections`).
- Hand-rolled MAVLink (no third-party SDK).
- Deterministic typed state machine for scan control: `ZoomedOut`, `ZoomedIn`, `TargetFollow`.
- Ego-motion compensation is mandatory for movement detection. Movement detection runs at **both** zoom-out and zoom-in (per-zoom-band thresholds; classical-CV adequacy at zoom-in is benchmark-gated).
- Operator workload cap of ≤5 POIs/minute is hard.
- Operator timeout scales with confidence.
- **Operator commands are authenticated, signed, and replay-protected** (modem encryption alone is not sufficient).
- Local VLM with structured `VlmAssessment` schema; no cloud egress.
- Always-on camera + telemetry stream to Ground Station.
- **Lost-link failsafe is explicit** (`mission_executor` runs a typed ladder; default RTL after 30 s grace).
- **Pre-flight self-test (BIT) gates takeoff** including MapObjects pre-flight pull.
- **MapObjects are mission-bracketed and centrally synchronised** via the `missions` API extension `/missions/{id}/mapobjects`.
- `autopilot` and `missions` are separate repos with a shared `mission-schema` artefact.
- No silent error swallowing; health endpoint reflects every dependency including `mapobjects_sync`.
- Geofence enforcement is symmetric: both INCLUSION and EXCLUSION are honoured.

---

## 5. Open questions

Surfaced explicitly in `architecture.md §8`:

| # | Question | Blocks |
|---|---|---|
| Q1 | Sweep pattern (pendulum / raster / lawn-mower), FOV per zoom tier, dwell time. | `scan_controller` zoom-out implementation. |
| Q2 | Ground Station API contract (stream protocol, auth, bbox-overlay rendering). | `telemetry_stream` + `operator_bridge` design. |
| Q3 | `mapobjects_store` engine (SQLite + H3 / KV / in-memory + snapshot). | Persistent-state design. |
| Q4 | Tier 1 contract evolution / `detection_client` versioning. | gRPC contract definition. |
| Q5 | `mission-schema` extraction location. | Schema sharing between `autopilot` and `missions`. |
| Q6 | MAVLink-2 message signing. | `mavlink_layer` startup handshake. |
| Q7 | Central MapObjects API contract details (paging, photo-ref upload, retention). | `missions` repo work + `mission_client` MapObjects sync code. |
| Q8 | MapObjects conflict resolution (projection rules, REMOVED-claim expiry, multi-class disambiguation). | Central `map_objects_current` view definition. |
| Q9 | Operator-command authentication scheme (HMAC vs ed25519 vs MAVLink-2 sig vs separate envelope). | `operator_bridge` validation logic + Ground Station integration. |
| Q10 | Software rollback policy on the airframe (boot-time check, A/B partition, watchdog rollback). | Deployment design + on-airframe service supervision. |
| Q11 | Multi-operator session policy (single active vs quorum). | `operator_bridge` session model. |
| Q12 | Comms blackout during banking turns (tolerate as `LinkDegraded` vs suppress lost-link during turns). | Lost-link ladder timing constants. |
| Q13 | All-season acceptance flight gates (minimum flights per season, per-season acceptance criteria). | MVP sign-off scope. |
| Q14 | Movement-detector zoom-in fallback selection (learned optical flow vs CNN motion-segmentation vs IMU-tighter classical CV) if classical CV fails the per-zoom-band FP cap. | `movement_detector` zoom-in scope. |

---

## 6. Suite-level docs autopilot consumes

These live in `../_docs/` (parent suite repo):

| Path | Used for |
|---|---|
| `../_docs/00_top_level_architecture.md` | Suite topology, edge tier, flight-gate convention. |
| `../_docs/02_missions.md` | Mission / Waypoint / Vehicle schemas (consumed by `mission_client`). |
| `../_docs/03_detections.md` | Detections gRPC API (consumed by `detection_client`). |
| `../_docs/04_system_design_clarifications.md` | REST patterns, stream-detection protocol, edge-device connection semantics. |
| `../_docs/11_gps_denied.md` | GPS-Denied service architecture (out of autopilot scope). |
| `../_docs/12_ai_training.md` | AI training pipeline (autopilot consumes the resulting models via the suite-wide model-sync timer). |

Full table with ownership: `architecture.md §10`.

---

## 7. Where to put new content

| You want to document… | Put it in… |
|---|---|
| A new flow between components | `system-flows.md` (and add a sequence diagram). |
| A new entity / schema | `data_model.md`. |
| A change in NFR target | `architecture.md §6`. |
| A change in a single component's responsibilities | `components/<name>/description.md`. |
| A change in the MAVLink command surface | `architecture.md §7.7`. |
| A new architectural principle | `architecture.md §5`. |
| A new design decision with research backing | `decision-rationale.md`. |
| A new term | `glossary.md`. |
| A change in deployment shape | `deployment/<file>.md`. |
| Ad-hoc internal team note | not in `_docs/`. |