# 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

- `GeoPoint` equality uses a tolerance of 0.00005° (~5.5m), which may cause false positives for closely-spaced tiles at high zoom levels
- `DatabaseConfig` is defined but never wired via DI — connection string is read directly from `IConfiguration`
- `ISatelliteDownloader` interface exists but is not implemented by `GoogleMapsDownloaderV2` (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.