# System Overview Diagram

> Date: 2026-05-24. Plain-English end-to-end view of the GPS-denied onboard pose estimation system, intended for onboarding and presentations. Detailed per-component decomposition lives in `architecture.md`; per-flow sequences in `system-flows.md`.

**One-line goal**: when a drone's GPS is jammed or spoofed, give the flight controller a position fix derived from what the camera sees vs. a pre-loaded satellite map — with an honest accuracy number attached.

```mermaid
flowchart LR
  subgraph BEFORE["Before flight — operator workstation"]
    UI["Mission Planner<br/>(operator draws route)"] --> PREP["Pre-flight setup<br/>• download map tiles<br/>• build search index<br/>• mark takeoff point"]
    SAT[("Satellite map service")] -. tiles .-> PREP
  end

  subgraph DURING["During flight — drone companion computer"]
    CAM[/"Camera<br/>(3 Hz)"/] --> MOTION["Motion tracker<br/>(camera + IMU →<br/>frame-to-frame motion)"]
    CAM --> MATCH["Map matcher<br/>(find where this frame is<br/>on the satellite map)"]
    FC[/"Flight controller"/] -- "IMU 100–200 Hz" --> MOTION
    FC -- "IMU 100–200 Hz" --> FUSE
    MOTION --> FUSE
    MATCH --> FUSE["State estimator<br/>(fuse motion + map +<br/>IMU into one position)"]
    FUSE == "Position + accuracy<br/>+ how we got it" ==> FC
    CACHE[("Cached map tiles<br/>read-only in flight")] --> MATCH
  end

  subgraph AFTER["After landing — operator workstation"]
    UPLOAD["Upload new tiles<br/>captured in flight<br/>(only on clean landing)"]
  end

  PREP ==> DURING
  PREP --> CACHE
  DURING -. flight log .-> UPLOAD
  UPLOAD -. tiles .-> SAT

  classDef ext fill:#eef,stroke:#88a;
  classDef store fill:#ffe,stroke:#aa6;
  class UI,SAT,FC,CAM ext;
  class CACHE store;
```

## How to read it in 30 seconds

1. **Before flight** — the operator draws a route in the Mission Planner. The workstation downloads the satellite-map tiles that cover the route, builds a search index over them, and notes the takeoff point.
2. **During flight** — the drone's camera produces a frame three times a second. Two things happen to each frame in parallel:
   - The **motion tracker** combines the camera with the flight controller's IMU to estimate how the drone moved since the last frame.
   - The **map matcher** compares the frame against the cached satellite tiles to find where on the map the drone currently is.
3. The **state estimator** fuses both signals (plus raw IMU) into a single position estimate, attaches an honest accuracy number, and sends it to the flight controller — which uses it as a drop-in replacement for GPS.
4. **After landing** — any new map tiles the drone captured during the flight get uploaded back to the satellite map service so the next mission has fresher data.

## Why the picture is shaped this way (invariants worth defending)

- **The drone never talks to the satellite map service in flight.** All tile downloads happen on the operator workstation before takeoff; all tile uploads happen on the operator workstation after landing. The airborne code physically cannot reach the network for tiles. (ADR-004 process isolation.)
- **Two parallel branches feed the estimator.** Motion tracking (camera + IMU) and map matching (camera + cached tiles) are independent — neither depends on the other to produce a result. The estimator decides how to weigh them on every frame.
- **The position emitted to the flight controller always carries an honest accuracy number and a provenance label** (`satellite_anchored` / `visual_propagated` / `dead_reckoned`). Under-reporting accuracy is treated as a defect, not a tuning knob.
- **Post-landing upload only fires on a clean shutdown** (the flight log's footer record confirms it). If the system crashed or the drone went down hard, mid-flight tiles stay local until an operator triages them.