mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-21 15:31:14 +00:00
Oleksandr Bezdieniezhnykh
b0fffa6d42
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>
110 lines
6.4 KiB
Markdown
110 lines
6.4 KiB
Markdown
# 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 |
|