# TileDownloader

## 1. High-Level Overview

**Purpose**: Acquires satellite imagery tiles from Google Maps, stores them on disk, and persists metadata to the database. Handles session tokens, concurrent downloads, retry logic, and tile deduplication. Since AZ-488 it also hosts the UAV upload pipeline: the `UavTileQualityGate` 5-rule validator and the `UavTileUploadHandler` that persists `source='uav'` rows via `ITileRepository.InsertAsync`.

**Architectural Pattern**: Service + Gateway (wraps external API with retry/throttling) + per-source quality gate (UAV upload path)

**csproj**: `SatelliteProvider.Services.TileDownloader/SatelliteProvider.Services.TileDownloader.csproj` (split out of the monolithic `SatelliteProvider.Services` project in epic AZ-309)

**Upstream dependencies**: Common (DTOs, Enums — `TileSource` + `TileSourceConverter` since AZ-484, plus `UavTileMetadata` / `UavTileBatchUploadResponse` / `UavTileRejectReasons` since AZ-488; GeoUtils; configs `MapConfig`, `StorageConfig`, `ProcessingConfig`, `UavQualityConfig`; RateLimitException), DataAccess (TileEntity, ITileRepository), SixLabors.ImageSharp 3.1.11 (UAV decode + variance check).

**Downstream consumers**: RegionProcessing and WebApi — both via `ITileService` from Common; WebApi also resolves `IUavTileQualityGate` and `IUavTileUploadHandler` from this component (DI only — no compile-time `ProjectReference` from any consumer to this project's concrete types).

## 2. Internal Interfaces

### Class: GoogleMapsDownloaderV2
| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `DownloadSingleTileAsync` | lat, lon, zoomLevel, CancellationToken | `DownloadedTileInfoV2` | Yes | ArgumentException, RateLimitException, HttpRequestException |
| `GetTilesWithMetadataAsync` | center, radiusM, zoom, existingTiles, CancellationToken | `List<DownloadedTileInfoV2>` | Yes | ArgumentException, RateLimitException, HttpRequestException |

### Service: TileService (implements ITileService)
| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `DownloadAndStoreTilesAsync` | lat, lon, sizeM, zoom, CancellationToken | `List<TileMetadata>` | Yes | propagated from downloader |
| `GetTileAsync` | Guid | `TileMetadata?` | Yes | NpgsqlException |
| `GetTilesByRegionAsync` | lat, lon, sizeM, zoom | `IEnumerable<TileMetadata>` | Yes | NpgsqlException |
| `GetOrDownloadTileAsync` (AZ-310) | z, x, y, CancellationToken | `TileBytes` | Yes | propagated from downloader |
| `DownloadAndStoreSingleTileAsync` (AZ-311) | lat, lon, zoom, CancellationToken | `TileMetadata` | Yes | propagated from downloader |

### Service: UavTileQualityGate (implements IUavTileQualityGate, AZ-488)
| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `Validate` | imageBytes, contentType, `UavTileMetadata` | `UavTileQualityResult` (accept + reason code) | No | none (decode exceptions caught and translated to `INVALID_FORMAT`) |

Rules run in fixed order (Format → Size band → Dimensions → Captured-at age → Blank/uniform); first failure short-circuits. Thresholds come from `UavQualityConfig`. Time comes from injected `TimeProvider` (defaults to `TimeProvider.System`) for deterministic tests.

### Service: UavTileUploadHandler (implements IUavTileUploadHandler, AZ-488)
| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `HandleAsync` | `metadataJson`, `IReadOnlyList<UavUploadFile>`, CancellationToken | `UavTileUploadHandlerResult` (envelope error OR per-item response) | Yes | propagated `IOException`/`UnauthorizedAccessException` per item, translated to per-item `STORAGE_FAILURE` |

Per-item flow: parse metadata JSON → reject envelope (mismatch, oversize, malformed JSON) OR run each item through `IUavTileQualityGate` → for accepted items, write JPEG to `{StorageConfig.TilesDirectory}/uav/{zoom}/{x}/{y}.jpg` then call `ITileRepository.InsertAsync` (per-source UPSERT) with `source='uav'` and the request-supplied `capturedAt`. File-before-row ordering keeps an orphan file (rather than a row pointing at nothing) when persistence fails.

## 4. Data Access Patterns

### Caching Strategy
| Data | Cache Type | TTL | Invalidation |
|------|-----------|-----|-------------|
| Tile bytes | In-memory (IMemoryCache, owned by TileService since AZ-310) | 1h absolute, 30min sliding | None (manual restart) |
| Tile metadata | Database | Append-by-source per cell (AZ-484); reads return most-recent across sources | Per-source UPSERT keyed on `(latitude, longitude, tile_zoom, tile_size_meters, source)` overwrites the existing same-source row and refreshes `captured_at` |
| Active downloads | ConcurrentDictionary | Duration of download | Removed on completion |

## 5. Implementation Details

**Algorithmic Complexity**: Tile grid calculation is O(w×h) where w×h is the number of tiles covering the bounding box.

**State Management**: `_activeDownloads` (ConcurrentDictionary) prevents duplicate concurrent downloads. `_downloadSemaphore` limits parallelism.

**Key Dependencies**:
| Library | Version | Purpose |
|---------|---------|---------|
| Newtonsoft.Json | 13.0.4 | Serialize session creation request body |
| IHttpClientFactory | built-in | Create HttpClient instances per request |

**Error Handling**:
- Exponential backoff retry for 429 (rate limit) and 5xx errors: 1s → 2s → 4s → 8s → 16s, max 30s, 5 retries
- Immediate throw for 401/403 (auth errors) and cancellation
- `RateLimitException` thrown after exhausting retries on 429

## 7. Caveats & Edge Cases

- `GoogleMapsDownloaderV2` is registered behind `ISatelliteDownloader` (resolved by AZ-310 cleanup); the previous concrete-type coupling is gone.
- User-Agent header spoofs Chrome — could be rejected if Google changes detection
- Allowed zoom levels hardcoded to [15,16,17,18,19] — throws for others
- Session token rotation threshold (100 tiles) is an educated guess; Google's actual limit is not documented
- Static `_activeDownloads` dictionary means deduplication is process-wide, surviving service scope boundaries

## 8. Dependency Graph

**Must be implemented after**: Common, DataAccess
**Can be implemented in parallel with**: nothing (needs both foundations)
**Blocks**: RegionProcessing

## 9. Logging Strategy

| Log Level | When | Example |
|-----------|------|---------|
| ERROR | Download failure, session token failure | `Tile download failed. Tile: (X, Y), Status: {StatusCode}` |
| WARN | Rate limiting retry | `Rate limited (429). Waiting {Delay}s before retry` |
| INFO | — | (no INFO-level logs in this component) |
