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/.