mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-21 13:11:15 +00:00
[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:
@@ -0,0 +1,71 @@
|
||||
# RegionProcessing
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Manages the lifecycle of geographic region tile requests — from API submission through a bounded queue to background processing that downloads tiles, generates CSV/summary files, and optionally stitches tiles into composite images.
|
||||
|
||||
**Architectural Pattern**: Producer-Consumer with Background Workers
|
||||
|
||||
**Upstream dependencies**: Common (DTOs, interfaces, configs, GeoUtils), DataAccess (RegionRepository), TileDownloader (ITileService)
|
||||
|
||||
**Downstream consumers**: RouteManagement (creates regions for route points and geofences), WebApi (RequestRegion/GetRegionStatus endpoints)
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### Service: RegionService (implements IRegionService)
|
||||
See Common component for interface definition. Key implementation details:
|
||||
- `RequestRegionAsync`: creates DB record, enqueues to bounded channel
|
||||
- `ProcessRegionAsync`: 5-minute timeout, comprehensive error handling, generates CSV + summary + optional stitched image
|
||||
|
||||
### BackgroundService: RegionProcessingService
|
||||
- `ExecuteAsync`: spawns N parallel workers (configurable via `MaxConcurrentRegions`) with staggered startup
|
||||
|
||||
### Queue: RegionRequestQueue (implements IRegionRequestQueue)
|
||||
- Bounded `Channel<RegionRequest>` with `BoundedChannelFullMode.Wait`
|
||||
|
||||
## 4. Data Access Patterns
|
||||
|
||||
### Queries
|
||||
| Query | Frequency | Hot Path | Index Needed |
|
||||
|-------|-----------|----------|--------------|
|
||||
| Region GetByIdAsync | Very High (per processing) | Yes | PK |
|
||||
| Region UpdateAsync (status transitions) | High | Yes | PK |
|
||||
| Region InsertAsync | Medium | No | — |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Region status tracked in database (queued → processing → completed/failed). Queue state is in-memory (Channel<T>).
|
||||
|
||||
**Key Dependencies**:
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| SixLabors.ImageSharp | 3.1.11 | Tile stitching into composite JPEG |
|
||||
| System.Threading.Channels | built-in | Bounded async queue |
|
||||
|
||||
**Error Handling**:
|
||||
- 5-minute processing timeout per region
|
||||
- Separate catch blocks for: timeout, external cancellation, rate limiting, HTTP errors, generic errors
|
||||
- All failures produce a summary file with error details and set status to "failed"
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- Queue is in-memory: pending requests are lost on process restart (no persistence)
|
||||
- 5-minute timeout is hardcoded, not configurable
|
||||
- Stitching crosshair is drawn with a fixed 10-pixel arm length (±5 pixels)
|
||||
- Region status "queued" in code vs "pending" mentioned in some API documentation
|
||||
- `RegionProcessingService` workers have random startup delay (100–500ms) to avoid thundering herd on queue
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: Common, DataAccess, TileDownloader
|
||||
**Can be implemented in parallel with**: nothing at this layer
|
||||
**Blocks**: RouteManagement (uses IRegionService to create regions)
|
||||
|
||||
## 9. Logging Strategy
|
||||
|
||||
| Log Level | When | Example |
|
||||
|-----------|------|---------|
|
||||
| ERROR | Processing failure | `Failed to process region {RegionId}` |
|
||||
| ERROR | Rate limit exceeded | `Rate limit exceeded for region {RegionId}` |
|
||||
| WARN | Region not found, missing tile file | `Region {RegionId} not found in database` |
|
||||
| INFO | Service start/stop, queue creation | `Region Processing Service started with {N} workers` |
|
||||
Reference in New Issue
Block a user