satellite-provider/_docs/02_document/modules/common_interfaces.md

Module: Common/Interfaces

Purpose

Service contracts defining the application's core operations. Implementations live in the per-component service projects (SatelliteProvider.Services.TileDownloader, SatelliteProvider.Services.RegionProcessing, SatelliteProvider.Services.RouteManagement). Cross-component runtime calls between Layer-3 components flow exclusively through these interfaces — there are no compile-time ProjectReference entries between the three sibling service projects.

Public Interface

ITileService

• DownloadAndStoreTilesAsync(double lat, double lon, double sizeMeters, int zoomLevel, CancellationToken) → Task<List<TileMetadata>>: downloads missing tiles for a region and returns all tile metadata (existing + new)
• GetTileAsync(Guid id) → Task<TileMetadata?>: retrieve a single tile by ID
• GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileMetadata>>: query tiles within a geographic region
• GetOrDownloadTileAsync(int z, int x, int y, CancellationToken) → Task<TileBytes>: serve a tile by Z/X/Y, hitting cache, then repository, then downloader (added in AZ-310)
• DownloadAndStoreSingleTileAsync(double latitude, double longitude, int zoomLevel, CancellationToken) → Task<TileMetadata>: download one tile by lat/lon and persist (added in AZ-311)
• GetInventoryAsync(TileInventoryRequest request, CancellationToken) → Task<TileInventoryResponse>: bulk per-cell metadata read for the POST /api/satellite/tiles/inventory endpoint (added AZ-505). Computes location_hash per request entry via Uuidv5.LocationHashForTile (Form A) or uses the caller-supplied hashes (Form B), delegates the read to ITileRepository.GetTilesByLocationHashesAsync, applies the AZ-484 / AZ-503-foundation most-recent-across-sources selection per cell, and shapes the result so response.results.length == request entry count in input order (see tile-inventory.md v1.0.0 Inv-2..Inv-6). XOR validation + entry-cap enforcement happen in the API handler, not here.

IRegionService

• RequestRegionAsync(Guid id, double lat, double lon, double sizeMeters, int zoomLevel, bool stitchTiles) → Task<RegionStatusResponse>: creates a region record and enqueues for async processing
• GetRegionStatusAsync(Guid id) → Task<RegionStatusResponse?>: retrieves current status of a region request
• ProcessRegionAsync(Guid id, CancellationToken) → Task: executes tile downloading, CSV/summary generation, optional stitching

IRouteService

• CreateRouteAsync(CreateRouteRequest request) → Task<RouteResponse>: validates input, calculates intermediate points, persists route + points, optionally creates geofence regions
• GetRouteAsync(Guid id) → Task<RouteResponse?>: retrieves route with all points

ISatelliteDownloader

• GetTiles(GeoPoint geoPoint, double radiusM, int zoomLevel, CancellationToken) → Task: legacy interface for tile downloading (not directly implemented by GoogleMapsDownloaderV2)

IRegionRequestQueue

• EnqueueAsync(RegionRequest request, CancellationToken) → ValueTask: add region request to the bounded queue
• DequeueAsync(CancellationToken) → ValueTask<RegionRequest?>: consume next request (blocks until available)
• Count (int): current queue depth

Internal Logic

Pure interface definitions — no logic.

Dependencies

• All interfaces reference DTOs from SatelliteProvider.Common.DTO

Consumers

• Program.cs — DI registration of implementations
• RegionProcessingService — consumes IRegionRequestQueue and IRegionService
• RouteService — consumes IRegionService (for geofence region creation)
• RouteProcessingService — consumes IRegionService via service provider scope
• API endpoints — consume ITileService, IRegionService, IRouteService

Data Models

None defined here.

Configuration

None.

External Integrations

None.

Security

None.

Tests

No dedicated interface tests.