# Module: Common/Configs

## Purpose
Configuration POCOs that bind to `appsettings.json` sections via `IOptions<T>` pattern.

## Public Interface

### MapConfig
- `Service` (string): map provider name (e.g., "GoogleMaps")
- `ApiKey` (string): API key for the map provider

### StorageConfig
- `TilesDirectory` (string): base path for tile storage (default: `/tiles`)
- `ReadyDirectory` (string): base path for output files (default: `/ready`)
- `GetTileSubdirectoryPath(int zoomLevel, int tileX, int tileY) → string`: computes bucketed subdirectory path (`{tiles}/{zoom}/{xBucket}/{yBucket}`) using integer division by 1000
- `GetTileFilePath(int zoomLevel, int tileX, int tileY, string timestamp) → string`: computes full file path with timestamped filename (`tile_{z}_{x}_{y}_{ts}.jpg`)

### ProcessingConfig
- `MaxConcurrentDownloads` (int, default: 4): semaphore limit for parallel tile downloads
- `MaxConcurrentRegions` (int, default: 3): parallel region processing workers
- `DefaultZoomLevel` (int, default: 20): fallback zoom level
- `QueueCapacity` (int, default: 100): bounded channel capacity for region request queue
- `DelayBetweenRequestsMs` (int, default: 50): throttle delay between Google Maps requests
- `SessionTokenReuseCount` (int, default: 100): tiles per session token before rotation

### DatabaseConfig
- `ConnectionString` (string): DB connection string (unused — connection string is resolved directly from `IConfiguration` in `Program.cs`)

### UavQualityConfig
Knobs for the 5-rule UAV tile quality gate (`UavTileQualityGate`) and the multipart upload envelope. Bound from the `UavQuality` section in `appsettings.json`.
- `MinBytes` (int, default: `5 * 1024` = 5 KiB): lower bound for Rule 2 (`SIZE_OUT_OF_BAND`).
- `MaxBytes` (int, default: `5 * 1024 * 1024` = 5 MiB): upper bound for Rule 2; also drives `KestrelServerOptions.Limits.MaxRequestBodySize = MaxBatchSize * MaxBytes` and `FormOptions.MultipartBodyLengthLimit` in `Program.cs`.
- `MaxAgeDays` (int, default: 7): Rule 4 cutoff for `CAPTURED_AT_TOO_OLD`.
- `CapturedAtFutureSkewSeconds` (int, default: 30): Rule 4 forward clock-skew tolerance for `CAPTURED_AT_FUTURE`.
- `MinLuminanceVariance` (double, default: 10.0): Rule 5 threshold for `IMAGE_TOO_UNIFORM` measured on a downsampled `L8` image.
- `MaxBatchSize` (int, default: 100): hard cap on per-request batch length; violations return 400 envelope-level (see AC-8, RL-05).
- `LuminanceSampleSize` (int, default: 32): edge length of the square downsample fed into Rule 5; keeps the per-item gate cost bounded.

## Internal Logic
`StorageConfig.GetTileSubdirectoryPath` buckets tiles by dividing X/Y coordinates by 1000, preventing filesystem performance degradation from too many files in one directory.

## Dependencies
None (pure POCOs, no internal imports).

## Consumers
- `Program.cs` — binds from config sections via `builder.Services.Configure<T>()`
- `GoogleMapsDownloaderV2` — reads `MapConfig`, `StorageConfig`, `ProcessingConfig` via `IOptions<T>`
- `RegionService` — reads `StorageConfig`
- `RegionProcessingService` — reads `ProcessingConfig`
- `RouteProcessingService` — reads `StorageConfig`
- `RegionRequestQueue` — receives `QueueCapacity` as constructor param

## Data Models
No domain entities; these are configuration DTOs.

## Configuration
These classes **define** the configuration shape consumed by all services.

| Config Class | appsettings Section |
|-------------|-------------------|
| MapConfig | `MapConfig` |
| StorageConfig | `StorageConfig` |
| ProcessingConfig | `ProcessingConfig` |
| DatabaseConfig | (not wired — connection string read directly) |
| UavQualityConfig | `UavQuality` (added in AZ-488; consumed by `UavTileQualityGate`, `UavTileUploadHandler`, and `Program.cs` request-size limits) |

## External Integrations
None.

## Security
`MapConfig.ApiKey` holds the Google Maps API key. In production, injected via environment variable `MapConfig__ApiKey`.

## Tests
No dedicated tests.