# External Integrations

**Analysis Date:** 2026-04-01

## APIs & External Services

**Satellite Tile Provider:**
- Google Maps Slippy Tile API — satellite imagery for navigation reference
  - URL pattern (actively in code): `https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={zoom}`
  - Used in: `src/gps_denied/core/satellite.py` (`SatelliteDataManager.fetch_tile`)
  - Auth: none in current code — the URL is called unauthenticated via the undocumented tile CDN
  - Config: `TILES_PROVIDER`, `TILES_API_KEY` env vars (key field exists in `TileProviderConfig` but not threaded into URL construction yet)
  - Note: docs specify Google Maps Tile API with a paid API key; current code hits the public CDN endpoint without a key. This is a mismatch — the key config is wired in `src/gps_denied/config.py` but not used in `satellite.py`.
  - Alternative providers documented (not implemented): Bing Maps, Mapbox Satellite

## Data Storage

**Databases:**
- SQLite (async) — primary operational datastore
  - Default connection: `sqlite+aiosqlite:///./flight_data.db` (relative to CWD)
  - Configurable via `DB_URL` env var (any SQLAlchemy async-compatible URL)
  - Client: SQLAlchemy >=2 async ORM (`src/gps_denied/db/engine.py`)
  - Session factory: `async_sessionmaker` in `src/gps_denied/db/engine.py`
  - Models: `src/gps_denied/db/models.py`
  - Migrations: Alembic >=1.14 (migration scripts directory not confirmed in scan)
  - SQLite pragmas: `PRAGMA foreign_keys=ON` enforced on every connection

**File Storage:**
- Local filesystem — satellite tile cache via diskcache
  - Cache directory: `.satellite_cache` (default) or `TILES_CACHE_DIR` env var
  - Size limit: 10GB default (configurable in `SatelliteDataManager.__init__`)
  - Key scheme: `{flight_id}_{zoom}_{x}_{y}` (PNG-encoded bytes)
  - Implementation: `src/gps_denied/core/satellite.py`
- Local filesystem — ML model weights
  - Directory: `weights/` (configurable via `MODEL_WEIGHTS_DIR` env var)

**Caching:**
- diskcache >=5.6 — disk-based LRU cache for satellite tiles
  - No in-memory cache layer (Redis/Memcached not used)

## Hardware Interfaces

**Camera (UAV):**
- Raw image frames ingested via REST API (`POST /flights/{id}/frames`) as multipart file uploads
- No direct camera SDK or hardware driver in codebase — hardware abstraction delegated to the flight controller or a separate capture process
- Frame format: image files (JPEG/PNG) decoded by OpenCV (`cv2.imdecode`)

**IMU:**
- IMU data referenced in architecture (`CameraParameters` schema, ESKF fusion design)
- No direct IMU hardware driver in current code — IMU input pathway not yet implemented
- Planned: multi-rate fusion at ~100Hz IMU vs ~3fps camera, implemented in custom ESKF

**GPU / CUDA (Jetson Orin Nano Super):**
- CUDA 12.6.10 — JetPack-bundled, accessed via OpenCV CUDA bindings and TensorRT
- TensorRT 10.3.0 — planned FP16 inference engine for SuperPoint, LightGlue, LiteSAM/XFeat
  - Wrapped behind `IModelManager.optimize_to_tensorrt()` interface in `src/gps_denied/core/models.py`
  - Current implementation uses `MockInferenceEngine` stubs
- NVIDIA VPI 3.2 — JetPack-bundled; planned as alternative to OpenCV CUDA for image resize (not yet used in code)

## Authentication & Identity

**Auth Provider:**
- None — no authentication on the REST API in current code
- CORS origins default to `["*"]` (`APIConfig` in `src/gps_denied/config.py`)
- Intended for local on-device operation (Jetson Orin Nano Super runs in air-gapped environment)

## Visual Odometry Engine

**PyCuVSLAM v15.0.0 (NVIDIA, closed-source):**
- Planned primary VO engine — SLAM with mono+IMU mode, loop closure, 116fps at 720p on Orin Nano
- Install: local aarch64 wheel from `bin/aarch64/` (not on PyPI)
- Abstracted behind `ISequentialVisualOdometry` interface in `src/gps_denied/core/vo.py`
- Not yet integrated — current `SequentialVisualOdometry` class uses SuperPoint+LightGlue via `ModelManager`
- Fallback if cuVSLAM fails: XFeat frame-to-frame matching (also not yet implemented)

## Factor Graph & Sensor Fusion

**GTSAM >=4.3a0:**
- Factor graph optimizer for route chunk pose graph optimization
- Used in `src/gps_denied/core/graph.py` (`FactorGraphOptimizer`)
- Import guarded with try/except — `HAS_GTSAM` flag allows graceful degradation
- Custom ESKF (16-state, NumPy/SciPy) is the planned primary fusion engine at 100Hz — not yet a separate file; referenced in docs only

## Streaming Protocol

**Server-Sent Events (SSE):**
- sse-starlette >=2.0 — `EventSourceResponse` used in `src/gps_denied/api/routers/flights.py`
- Streams real-time geolocalization results to a connected client during frame processing
- SSE utility helpers in `src/gps_denied/core/sse.py`
- No WebSocket or polling fallback

## Output Format

**GeoJSON (RFC 7946):**
- Primary coordinate output format (WGS84)
- `geojson` Python package planned (not yet in `pyproject.toml`)
- GPS coordinates returned in API responses via Pydantic schemas (`GPSPoint`, `ObjectGPSResponse`)

**CSV:**
- Documented as secondary export option; not yet implemented

## Tile Indexing Strategy

**Mercator / Slippy Tile Coordinates:**
- Web Mercator projection (XYZ tile scheme, same as Google Maps / OSM)
- Conversion utilities in `src/gps_denied/utils/mercator.py` (`latlon_to_tile`, `compute_tile_bounds`)
- Called from `src/gps_denied/core/satellite.py`

**GeoHash Indexing (planned, not yet implemented):**
- Docs specify `{geohash}/{zoom}_{x}_{y}.jpg` directory structure for pre-flight tile storage
- `pygeohash` package planned but not in `pyproject.toml`
- Current implementation uses diskcache flat-key scheme instead

## CI/CD & Deployment

**Hosting:**
- On-device: NVIDIA Jetson Orin Nano Super (air-gapped during flight)
- Development: x86_64 Linux with Docker+CUDA

**CI Pipeline:**
- Not detected in scanned directories (no `.github/`, `.gitlab-ci.yml`, etc. found)

## Environment Configuration

**Required env vars (non-default critical settings):**
- `DB_URL` — override default SQLite path for production
- `TILES_API_KEY` — Google Maps API key (currently unused in tile fetch code — see mismatch note above)
- `MODEL_WEIGHTS_DIR` — path to TensorRT/ONNX model weight files
- `AREA_*` — operational area bounding box (defaults to Eastern Ukraine: lat 45-52, lon 22-40)

**Secrets location:**
- `.env` file in project root (not committed — standard pydantic-settings pattern)

## Webhooks & Callbacks

**Incoming:**
- None

**Outgoing:**
- None — system is self-contained on the UAV; results streamed to connected client via SSE

---

*Integration audit: 2026-04-01*