azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 13:41:15 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
dceaddc436f236bf4549fd35f990f8c5cc694359
satellite-provider/_docs/02_document/modules/common_interfaces.md
T
Oleksandr Bezdieniezhnykh 5d84d2839e
ci/woodpecker/push/01-test Pipeline was successful
Details
ci/woodpecker/push/02-build-push Pipeline was successful
Details
[AZ-505] Test-spec sync + task-mode doc updates for cycle 6 
Step 12 (Test-Spec Sync, cycle-update mode):
- blackbox-tests.md: append BT-23..BT-26 for AZ-505's new
  observable behaviors (inventory order/shape; leaflet
  most-recent via location_hash; HTTP/2 multiplex over TLS+ALPN;
  request validation).
- performance-tests.md: append PT-09 (inventory p95 ≤ 1000ms /
  2500 tiles); records cycle-6 measured p95=66ms; documents
  promotion path to scripts/run-performance-tests.sh if budget
  ever tightens.
- traceability-matrix.md: resolve the 5 AZ-503 deferrals
  (AC-5/6/9/10/12) by pointing at AZ-505 test names + add 7
  AZ-505 AC rows (AC-1..AC-7) + bump totals (90 -> 94 tests,
  56/56 -> 63/63 in-scope) + add cycle-6 coverage shape notes
  (budget relaxation rationale, voting-filter deferral note,
  TLS+ALPN pivot, NFR propagation).

Step 13 (Update Docs, task mode):
- common_dtos.md: add 5 new TileInventory DTOs.
- common_interfaces.md: add ITileService.GetInventoryAsync.
- services_tile_service.md: document TileService.GetInventoryAsync
  steps + the XOR-validation-in-handler note.
- dataaccess_migrator.md: bump migration count 14 -> 15;
  describe migration 015 (AZ-505 leaflet covering index, lock
  window, INCLUDE-list trade-off).
- system-flows.md: add F7 (Leaflet Tile Serving, AZ-310 +
  AZ-505 location_hash rewire + TLS+ALPN) and F8 (Tile
  Inventory Bulk Lookup) with sequence diagrams, validation
  surface, and AC-4 perf evidence. Update Flow Inventory +
  Dependencies tables accordingly.
- glossary.md: add "Tile Inventory" entry pointing at the
  v1.0.0 contract.
- ripple_log_cycle6.md: new file — exhaustive reverse-dependency
  analysis confirms zero stale downstream module docs.

Advance autodev state from step 11 -> 14 (skipping 12+13 as
completed in this commit; auto-chain through Step 14 = Security
Audit optional gate).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-12 22:29:22 +03:00

3.9 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink