# Satellite Provider — Documentation Report

## Executive Summary

Full bottom-up documentation of the Satellite Provider service — a .NET 10 backend (migrated from .NET 8 LTS by AZ-500 in cycle 4) that pre-downloads, caches, and composites satellite imagery for a GPS-denied UAV navigation system. The analysis identified 5 logical components across 16 modules, documented 6 system flows, and produced a complete data model, deployment guide, and architecture reference.

## Problem Statement

UAVs operating without GPS need pre-cached satellite imagery for visual positioning. This service automates tile acquisition from satellite imagery providers (first implementation: Google Maps), organizes tiles by coordinates/zoom, generates composite maps for routes and regions, and will accept UAV-captured imagery (Layer 2) for improved accuracy. The downloader is provider-agnostic via `ISatelliteDownloader`.

## Architecture Overview

Single-instance containerized monolith with layered architecture (API → Services → DataAccess → PostgreSQL) and asynchronous background processing via in-process queues. No authentication (internal/trusted network service).

**Technology stack**: C# 14 / .NET 10 (cycle 4 — was C# 12 / .NET 8.0 through cycle 3), ASP.NET Core Minimal API, PostgreSQL 16, Dapper, Docker, Woodpecker CI

**Deployment**: Docker Compose (API + PostgreSQL), ARM64 primary, self-hosted registry

## Component Summary

| # | Component | Purpose | Dependencies |
|---|-----------|---------|-------------|
| 01 | Common | Shared DTOs, interfaces, configs, geospatial math | — |
| 02 | DataAccess | PostgreSQL persistence via Dapper + DbUp migrations | Common |
| 03 | TileDownloader | Provider-agnostic satellite tile acquisition with dedup | Common, DataAccess |
| 04 | RegionProcessing | Batch tile downloads, stitching, CSV/summary output | Common, DataAccess, TileDownloader |
| 05 | RouteManagement | Route interpolation, geofencing, consolidated map output | Common, DataAccess, RegionProcessing |
| — | WebApi | HTTP endpoints, DI configuration, startup | All above |

**Dependency layering** (bottom-up):
1. Common (foundation)
2. DataAccess (persistence)
3. TileDownloader (domain services)
4. RegionProcessing, RouteManagement (application/orchestration)
5. WebApi (entry point)

## System Flows

| Flow | Description | Key Components |
|------|-------------|---------------|
| Single Tile Download | Client requests tile by lat/lon/zoom; cache check → download → store | WebApi, TileDownloader, DataAccess |
| Region Request | Submit region definition; queued for async processing | WebApi, RegionProcessing |
| Region Processing | Background: calculate grid → download tiles → stitch → output files | RegionProcessing, TileDownloader |
| Route Creation | Submit waypoints; interpolate points, persist | WebApi, RouteManagement |
| Route Map Processing | Background: geofence filter → create regions → wait → ZIP | RouteManagement, RegionProcessing |
| Status Query | Poll region/route by ID | WebApi, DataAccess |

## Risk Summary

| Level | Count | Key Risks |
|-------|-------|-----------|
| High | 1 | Queue state lost on restart (in-process Channel, no persistence) |
| Medium | 2 | Single-instance limitation; no retry persistence for failed tiles |
| Low | 2 | No auth layer; MGRS/Upload endpoints are stubs |

## Test Coverage

| Component | Unit Tests | Integration Tests |
|-----------|-----------|------------------|
| Common | None | Indirect |
| DataAccess | None | Indirect (via integration) |
| TileDownloader | Placeholder only | Tile download tests |
| RegionProcessing | None | Region processing tests (multiple sizes/zooms) |
| RouteManagement | None | Basic, complex, extended route tests |

**Gap**: Unit test coverage is minimal (placeholder only). Integration tests provide the primary verification via Docker Compose.

## Key Decisions

| # | Decision | Rationale | Alternatives Rejected |
|---|----------|-----------|----------------------|
| 1 | Minimal API (no controllers) | Small endpoint surface, less ceremony | MVC controllers |
| 2 | Dapper over EF Core | Raw SQL control, performance, simplicity | Entity Framework (too heavy for this use case) |
| 3 | In-process Channel queue | No external dependencies, single instance | RabbitMQ, Redis queues |
| 4 | File-based tile storage | Fast reads, simple backup, immutable files | Blob storage, DB binary |
| 5 | Background hosted services | Clean lifecycle, framework-managed | Separate worker process |
| 6 | Provider-agnostic downloader interface | Future provider flexibility | Hardcoded Google Maps calls |

## Open Questions

| # | Question | Impact | Owner |
|---|----------|--------|-------|
| 1 | Which additional satellite imagery providers will be integrated? | New `ISatelliteDownloader` implementations needed | Product |
| 2 | Layer 2 upload: what orthogonal tile format/metadata will UAVs provide? | Upload endpoint design | Product |
| 3 | MGRS endpoint: what coordinate conversion library to use? | Implementation of tile-by-MGRS | Engineering |
| 4 | Should queue state survive restarts (persistent queue)? | Data loss risk on crash during processing | Engineering |

## Artifact Index

| File | Description |
|------|-------------|
| `_docs/00_problem/problem.md` | Problem statement |
| `_docs/00_problem/restrictions.md` | Constraints and dependencies |
| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria |
| `_docs/00_problem/data_parameters.md` | Input/output data schemas |
| `_docs/01_solution/solution.md` | Solution overview with per-component analysis |
| `_docs/02_document/00_discovery.md` | Codebase discovery (structure, deps, tech stack) |
| `_docs/02_document/architecture.md` | Full architecture document |
| `_docs/02_document/system-flows.md` | System flows with sequence diagrams |
| `_docs/02_document/data_model.md` | Database schema and migration history |
| `_docs/02_document/glossary.md` | Domain and technical glossary |
| `_docs/02_document/module-layout.md` | File ownership and layering map |
| `_docs/02_document/04_verification_log.md` | Verification results |
| `_docs/02_document/modules/*.md` | Per-module documentation (16 files) |
| `_docs/02_document/components/*/description.md` | Per-component specs (5 files) |
| `_docs/02_document/diagrams/components.md` | Component relationship diagram |
| `_docs/02_document/deployment/containerization.md` | Docker setup |
| `_docs/02_document/deployment/ci_cd_pipeline.md` | Woodpecker CI pipeline |
| `_docs/02_document/deployment/environment_strategy.md` | Environment config |