# 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.