satellite-provider/_docs/02_document/FINAL_report.md

Satellite Provider — Documentation Report

Executive Summary

Full bottom-up documentation of the Satellite Provider service — a .NET 8.0 backend 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# 12 / .NET 8.0, 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