[AZ-284] Autodev baseline + testability refactor

Phase A baseline outputs from /autodev (Steps 1-5):
- Problem & solution docs (_docs/00_problem, _docs/01_solution)
- Codebase documentation (_docs/02_document) incl. architecture,
  module-layout, glossary, system-flows, baseline compliance scan
- Test specs (blackbox, performance, resilience, security, resource,
  traceability matrix)
- Test task decomposition (_docs/02_tasks/todo): AZ-285..AZ-290
- Testability refactor (_docs/04_refactoring/01-testability-refactoring):
  - TC-01 Move DownloadedTileInfoV2 + new ExistingTileInfo to Common.DTO
  - TC-02 Replace dead ISatelliteDownloader API with real signatures
  - TC-03 GoogleMapsDownloaderV2 implements ISatelliteDownloader
  - TC-04 TileService depends on ISatelliteDownloader (mockable)
  - TC-05 DI + endpoints use ISatelliteDownloader
- Test runner scripts (scripts/run-tests.sh, run-performance-tests.sh)
- Autodev state pointer (_docs/_autodev_state.md)

Prepares the codebase for AZ-285..AZ-290 unit/integration test work.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-10 04:44:08 +03:00
parent 25a644a9bf
commit b0fffa6d42
68 changed files with 4192 additions and 11 deletions
+36
View File
@@ -0,0 +1,36 @@
# Problem Statement
## What is the system?
Satellite Provider is a backend service that supplies satellite imagery to a GPS-denied UAV navigation system. It pre-downloads and caches satellite tiles from external imagery providers (Layer 1) and will accept UAV-captured nadir camera imagery (Layer 2) uploaded post-flight. The downloader component is implementation-agnostic — the architecture supports multiple satellite imagery providers (e.g., Google Maps) via the `ISatelliteDownloader` interface.
## What problem does it solve?
UAVs operating without GPS rely on visual navigation by matching real-time camera imagery against pre-existing satellite maps. This requires:
1. **Pre-mission planning**: satellite imagery for the planned route must be downloaded and available before flight, regardless of which imagery provider is used
2. **Post-mission ingestion**: ground truth imagery captured during flight must be stored for future reference and improved accuracy
3. **Tile management**: imagery must be organized by geographic coordinates and zoom level, deduplicated, and served efficiently
4. **Provider flexibility**: the system must not be locked to a single satellite imagery source — providers may change or multiply
Without this service, operators would need to manually download and organize satellite imagery — an error-prone process that doesn't scale to multiple routes or large coverage areas.
## Who are the users?
- **GPS-Denied Navigation Service** — the primary consumer, requesting tiles for route planning and accessing cached imagery for visual positioning
- **Mission Planners** — define routes and regions to pre-download satellite coverage
- **UAV Systems** (planned) — upload nadir camera tiles post-flight for Layer 2 enrichment
## How does it work at a high level?
1. A client defines a geographic area (region) or path (route) via the REST API
2. The service calculates which satellite tiles are needed to cover that area
3. Tiles are downloaded from the configured satellite imagery provider (abstracted via `ISatelliteDownloader` interface; e.g., Google Maps)
4. Tiles are stored on disk and indexed in PostgreSQL
5. Optionally, tiles are stitched into composite images and packaged as ZIP archives
6. The client polls for completion and retrieves output artifacts
For routes, the service additionally:
- Interpolates intermediate points every ~200m along the path
- Applies geofence filters to limit tile downloads to areas of interest
- Generates consolidated route maps with geofence overlays