# Solution

The solution for `autopilot` is captured **in full** in `_docs/02_document/architecture.md`, `_docs/02_document/system-flows.md`, `_docs/02_document/data_model.md`, `_docs/02_document/decision-rationale.md`, the 13 per-component specs under `_docs/02_document/components/`, and `_docs/02_document/glossary.md`. These were produced before the canonical greenfield Problem step and were confirmed by the user on 2026-05-17.

This file is the **canonical greenfield Solution pointer** — it exists so downstream skills that expect `_docs/01_solution/solution.md` (test-spec, decompose, plan-resume) have a single entry point, and it summarises the decision shape; it does not duplicate the architecture.

## What is the solution

A single Rust binary on Jetson Orin Nano Super (aarch64) that runs the mission, drives the gimbal in a two-level scan loop, ingests RTSP, delegates Tier 1 detection to `../detections` over bi-directional gRPC, runs Tier 2 + optional Tier 3 (VLM) locally, talks to a remote operator over modem via an always-on telemetry stream, and bracket-synchronises a local H3-indexed MapObjects store with the central `missions` API. The dominant pattern is a deterministic typed state machine — `ZoomedOut`, `ZoomedIn { roi, hold_started_at }`, `TargetFollow { target_id, started_at }` — coordinating a small set of Tokio actor components.

## Component breakdown

13 components organised into four planes (see `architecture.md §2`, §3 and per-component specs):

- **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 contracts (inputs, outputs, state, failure modes, NFRs) live in `_docs/02_document/components/<name>/description.md`.

## Tech stack rationale (one-line summary per choice; full rationale in `decision-rationale.md`)

| Layer | Selection | Rationale |
|---|---|---|
| Language | Rust | Memory safety, performance, single-binary deployment, strong typing for the deterministic state machine. |
| Tier 1 detector | YOLO26 + YOLOE-26 FP16 TensorRT (in `../detections`) | Best fit with acceptance criteria + existing export pipeline. Not owned by autopilot. |
| Tier 2 analyzer | Primitive graph + lightweight ROI CNN | Fast, explainable, data-efficient. |
| Movement detection | OpenCV optical flow + telemetry; learned-CV fallback per Q14 | Addresses moving-camera constraint directly; benchmark-gated. |
| VLM runtime | NanoLLM / VILA1.5-3B (optional, local IPC) | Local multimodal path that matches the no-cloud requirement. |
| MAVLink transport | Hand-rolled (Rust) | Eliminates the largest current dependency-risk item; command surface is small (`architecture.md §7.7`). |
| Gimbal protocol | ViewPro A40 vendor protocol over UDP | Matches the deployed camera. |
| Inter-component IPC | Tokio channels / actors | Idiomatic Rust async. |
| External IPC (VLM) | Unix-domain socket + peer-credential check | Local-only authorisation. |
| MapObjects engine | TBD (SQLite + H3 / KV / in-memory + snapshot) | Open question Q3; does not block decomposition of the rest of the system. |
| Observability | `tracing` + JSON logs to stdout | Scraped by the deployment's log-shipping stack. |
| Build | `cargo` cross-compile for `aarch64-unknown-linux-gnu` | See `_docs/02_document/deployment/ci_cd_pipeline.md`. |

## Reading order for downstream skills

1. `_docs/02_document/architecture.md` — start with §0 Synopsis, then §3 Components, §5 Architectural Principles, §6 NFR Targets, §7 Detailed Design (in section order).
2. `_docs/02_document/system-flows.md` — flow-by-flow walkthroughs; cross-referenced from the architecture sections.
3. `_docs/02_document/data_model.md` — canonical entities (Frame, Detection, POI, VlmAssessment, MapObject, IgnoredItem, MissionItem, ...).
4. `_docs/02_document/components/<name>/description.md` — one per component; consumed by `/decompose` to map tasks to components.
5. `_docs/02_document/glossary.md` — project-specific terms (also user-confirmed 2026-05-17).
6. `_docs/02_document/decision-rationale.md` — load-bearing research and decision evidence (the equivalent of `research/` Mode A + Mode B outputs).

## Open questions / open decisions

Tracked in `_docs/02_document/architecture.md §8 Open Questions` (Q1–Q14). None of them block initial implementation decomposition; each component spec calls out the questions it depends on and what the temporary contract is until the question resolves.
