# Satellite Service

## 1. High-Level Overview

**Purpose**: Own the onboard boundary to the suite Satellite Service: import pre-flight mission cache packages, upload generated-tile packages after flight, and convert query frames into ranked local VPR candidates using preloaded DINOv2-VLAD descriptors and FAISS.

**Architectural Pattern**: Offline sync gateway + local retrieval index adapter.

**Upstream dependencies**: Camera ingest/calibration, Tile Manager, safety/anchor wrapper, Azaion Suite Satellite Service before/after flight.

**Downstream consumers**: Anchor verification, FDR.

## 2. Internal Interfaces

### Interface: `SatelliteService`

| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `import_mission_cache` | `CacheImportRequest` | `CacheImportResult` | Yes | `SyncUnavailable`, `PackageInvalid` |
| `upload_generated_tiles` | `GeneratedTileUploadRequest` | `GeneratedTileUploadResult` | Yes | `SyncUnavailable`, `PackageRejected` |
| `retrieve` | `RetrievalRequest` | `RetrievalResult` | Yes | `IndexUnavailable`, `DescriptorFailed` |
| `load_index` | `IndexLoadRequest` | `IndexStatus` | No | `ManifestInvalid`, `IndexUnavailable` |

**Input DTOs**:

```yaml
RetrievalRequest:
  frame: FramePacket
  prior_estimate: PositionEstimate optional
  search_radius_m: number optional
  max_candidates: integer
```

**Output DTOs**:

```yaml
RetrievalResult:
  query_descriptor_id: string
  candidates: list[VprCandidate]

VprCandidate:
  chunk_id: string
  tile_id: string
  score: number
  footprint: geometry
  freshness_status: enum
```

## 3. Data Access Patterns

| Query | Frequency | Hot Path | Index Needed |
|-------|-----------|----------|--------------|
| Top-K FAISS search | Triggered only | No steady-state | FAISS index |
| Import/export package sync | Pre-flight / post-flight only | No mid-flight | Package manifest and sidecar hashes |
| Load chunk metadata | Per candidate | No | PostgreSQL/PostGIS spatial and chunk indexes |

## 4. Implementation Details

**State Management**: Holds loaded descriptor model and FAISS index handles; tracks pre-flight import and post-flight upload package status.

**Key Dependencies**:

| Library | Purpose |
|---------|---------|
| DINOv2 / ONNX / TensorRT candidate path | Query descriptor extraction |
| FAISS CPU | Top-K retrieval |
| Satellite Service client | Pre-flight cache import and post-flight generated-tile upload |

**Error Handling Strategy**:
- If descriptor extraction or index load fails, return no candidates and trigger degraded mode.
- Optimized engines are allowed only after descriptor-fidelity tests pass.
- Network/package sync failures are allowed only before takeoff or after landing; during flight, the component must never call a satellite provider or suite service.

## 5. Caveats & Edge Cases

**Known limitations**:
- VPR result is only a candidate, never an accepted fix.
- Cross-domain retrieval can be wrong under seasonal, lighting, or terrain ambiguity.
- External Satellite Service availability cannot be part of the mid-flight localization safety case.

**Performance bottlenecks**:
- Descriptor extraction on Jetson must be trigger-limited and profiled separately from BASALT.

## 6. Dependency Graph

**Must be implemented after**: cache manifest/index schema, camera frame DTOs.

**Can be implemented in parallel with**: anchor verification.

**Blocks**: satellite relocalization flow.

## 7. Logging Strategy

| Log Level | When | Example |
|-----------|------|---------|
| ERROR | Index unavailable | `faiss_index_unavailable id=...` |
| WARN | No candidates | `vpr_no_candidates frame_id=...` |
| INFO | Retrieval invoked | `vpr_query candidates=... latency_ms=...` |

**Log format**: FDR structured event.

**Log storage**: FDR segment.