satellite-provider/_docs/02_document/modules/common_configs.md

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.