satellite-provider/_docs/02_document/components/05_route_management/description.md

RouteManagement

1. High-Level Overview

Purpose: Creates routes from user-defined waypoints, calculates intermediate points along the path, manages geofence regions, and generates consolidated route maps (stitched images, CSVs, summaries, ZIP archives) from completed region tile data.

Architectural Pattern: Service + Background Poller

Upstream dependencies: Common (DTOs, GeoUtils, configs), DataAccess (RouteRepository, RegionRepository), RegionProcessing (IRegionService for region creation)

Downstream consumers: WebApi (CreateRoute/GetRoute endpoints)

2. Internal Interfaces

Service: RouteService (implements IRouteService)

See Common component for interface definition. Key implementation details:

• CreateRouteAsync: validates, interpolates points every ≤200m, persists, creates geofence grid regions
• GetRouteAsync: reads route + points from DB

BackgroundService: RouteProcessingService

• ExecuteAsync: polls every 5 seconds for routes with request_maps=true AND maps_ready=false
• ProcessRouteSequentiallyAsync: checks region completion, retries failed regions, generates maps when ready

4. Data Access Patterns

Queries

Query	Frequency	Hot Path	Index Needed
GetRoutesWithPendingMapsAsync (polling)	Every 5s	No	(request_maps, maps_ready)
GetRoutePointsAsync	Per route processing	Yes	(route_id, sequence_number)
GetRegionIdsByRouteAsync	Per route processing	Yes	(route_id)
InsertRoutePointsAsync (bulk)	Per route creation	No	—

5. Implementation Details

Algorithmic Complexity: Point interpolation is O(n×m) where n = input points and m = max intermediate points per segment. Geofence grid creation is O(latSteps × lonSteps). Route-region matching uses O(points × regions) nearest-neighbor.

State Management: Route state tracked in database (request_maps, maps_ready flags). Processing is polling-based (not queue-based like regions).

Key Dependencies:

Library	Version	Purpose
SixLabors.ImageSharp	3.1.11	Route map stitching with geofence borders and route markers
System.IO.Compression	built-in	ZIP archive creation for tiles

Error Handling:

• Route creation validates: min 2 points, size range, name required, geofence coordinate validity
• RouteProcessingService catches exceptions per-route and continues to next
• Failed regions are retried by creating new region requests
• Tile coordinate extraction from filenames has a fallback returning (-1,-1) for unparseable names

7. Caveats & Edge Cases

• 200m max point spacing is hardcoded constant (MAX_POINT_SPACING_METERS)
• Polling interval (5s) is hardcoded
• RouteProcessingService resolves IRegionService via IServiceProvider.CreateScope() to avoid circular DI
• Route map stitching extracts tile coordinates from filenames (tile_{z}_{x}_{y}_{ts}.jpg); format change would break stitching
• ZIP creation runs on Task.Run (ThreadPool) — could consume a thread for large archives
• MatchRegionsToRoutePoints uses O(n²) nearest-neighbor matching; could be slow for routes with many points
• Region file cleanup deletes individual region CSVs/summaries after consolidation into route-level files
• catch in ExtractTileCoordinatesFromFilename silently swallows all exceptions

8. Dependency Graph

Must be implemented after: Common, DataAccess, RegionProcessing Can be implemented in parallel with: nothing Blocks: nothing (top of the dependency chain alongside WebApi)

9. Logging Strategy

Log Level	When	Example
ERROR	Route processing failure	Error processing route {RouteId}
WARN	Missing tile files, route not found, parse failures	Tile file not found: {FilePath}
INFO	Processing complete, CSV/summary/zip generated	Route {RouteId} maps processing completed