Oleksandr Bezdieniezhnykh
b0fffa6d42
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>
3.8 KiB
Common (Foundation)
1. High-Level Overview
Purpose: Shared foundation layer containing configuration POCOs, data transfer objects, service interface contracts, and geographic computation utilities used by all other components.
Architectural Pattern: Shared Kernel / Contracts Library
Upstream dependencies: None (leaf)
Downstream consumers: DataAccess, TileDownloader, RegionProcessing, RouteManagement, WebApi, Tests
2. Internal Interfaces
This component defines the service contracts that other components implement:
Interface: ITileService
| Method | Input | Output | Async | Error Types |
|---|---|---|---|---|
DownloadAndStoreTilesAsync |
lat, lon, sizeMeters, zoomLevel, CancellationToken | List<TileMetadata> |
Yes | Exception |
GetTileAsync |
Guid id | TileMetadata? |
Yes | Exception |
GetTilesByRegionAsync |
lat, lon, sizeMeters, zoomLevel | IEnumerable<TileMetadata> |
Yes | Exception |
Interface: IRegionService
| Method | Input | Output | Async | Error Types |
|---|---|---|---|---|
RequestRegionAsync |
id, lat, lon, sizeMeters, zoomLevel, stitchTiles | RegionStatus |
Yes | Exception |
GetRegionStatusAsync |
Guid id | RegionStatus? |
Yes | Exception |
ProcessRegionAsync |
Guid id, CancellationToken | void | Yes | RateLimitException, HttpRequestException, TimeoutException |
Interface: IRouteService
| Method | Input | Output | Async | Error Types |
|---|---|---|---|---|
CreateRouteAsync |
CreateRouteRequest |
RouteResponse |
Yes | ArgumentException |
GetRouteAsync |
Guid id | RouteResponse? |
Yes | Exception |
Interface: IRegionRequestQueue
| Method | Input | Output | Async | Error Types |
|---|---|---|---|---|
EnqueueAsync |
RegionRequest, CancellationToken |
void | Yes | OperationCanceledException |
DequeueAsync |
CancellationToken | RegionRequest? |
Yes | OperationCanceledException |
Static: GeoUtils
| Method | Input | Output | Async | Error Types |
|---|---|---|---|---|
WorldToTilePos |
GeoPoint, zoom | (x, y) | No | - |
TileToWorldPos |
x, y, zoom | GeoPoint | No | - |
CalculateIntermediatePoints |
start, end, maxSpacing | List<GeoPoint> |
No | - |
CalculateDistance |
p1, p2 | double (meters) | No | - |
GetBoundingBox |
center, radiusM | (minLat, maxLat, minLon, maxLon) | No | - |
DirectionTo (ext) |
p1, p2 | Direction | No | - |
GoDirection (ext) |
start, direction | GeoPoint | No | - |
3. External API Specification
N/A — internal-only component.
4. Data Access Patterns
N/A — no data access.
5. Implementation Details
State Management: Stateless (pure data types and static utilities)
Key Dependencies: None (no NuGet packages)
Algorithmic Complexity: GeoUtils uses Haversine formula (O(1) per calculation). CalculateIntermediatePoints is O(n) where n = ceil(distance / maxSpacing).
6. Extensions and Helpers
| Helper | Purpose | Used By |
|---|---|---|
| GeoUtils | Coordinate conversions, distance/bearing math, point interpolation | TileDownloader, RegionProcessing, RouteManagement, WebApi |
7. Caveats & Edge Cases
GeoPointequality uses a tolerance of 0.00005° (~5.5m), which may cause false positives for closely-spaced tiles at high zoom levelsDatabaseConfigis defined but never wired via DI — connection string is read directly fromIConfigurationISatelliteDownloaderinterface exists but is not implemented byGoogleMapsDownloaderV2(legacy artifact)
8. Dependency Graph
Must be implemented after: nothing Can be implemented in parallel with: DataAccess Blocks: TileDownloader, RegionProcessing, RouteManagement, WebApi
9. Logging Strategy
N/A — no logging in this component.