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

Module: Api/Program.cs

Purpose

Application entry point. Configures DI container, sets up middleware, defines minimal API endpoints, runs database migrations on startup, and starts background services.

Public Interface

API Endpoints

Method	Route	Handler	Description
GET	/tiles/{z}/{x}/{y}	ServeTile	Slippy map tile server with in-memory caching
GET	/api/satellite/tiles/latlon	GetTileByLatLon	Download single tile by lat/lon/zoom
GET	/api/satellite/tiles/mgrs	GetSatelliteTilesByMgrs	MGRS stub (returns empty)
POST	/api/satellite/upload	UploadImage	Image upload stub (returns Success: false)
POST	/api/satellite/request	RequestRegion	Queue region for async tile processing
GET	/api/satellite/region/{id}	GetRegionStatus	Get region processing status
POST	/api/satellite/route	CreateRoute	Create route with intermediate points
GET	/api/satellite/route/{id}	GetRoute	Get route with all points

Local Records (defined in Program.cs)

• GetSatelliteTilesResponse, SatelliteTile — MGRS response stubs
• UploadImageRequest — multipart form data request
• SaveResult — upload response stub
• DownloadTileResponse — tile download response
• RequestRegionRequest — region request body
• ParameterDescriptionFilter — Swagger operation filter

Internal Logic

DI Registration

1. Serilog configured from appsettings.json
2. Connection string extracted from ConnectionStrings:DefaultConnection
3. Config bindings: MapConfig, StorageConfig, ProcessingConfig
4. Singletons: repositories (TileRepository, RegionRepository, RouteRepository), GoogleMapsDownloaderV2, ITileService, IRegionService, IRouteService
5. IRegionRequestQueue with configurable capacity
6. Hosted services: RegionProcessingService, RouteProcessingService
7. CORS policy: TilesCors — configured origins from CorsConfig:AllowedOrigins, falls back to allow-any
8. JSON options: camelCase, case-insensitive
9. JWT authentication (AZ-487): AddSatelliteJwt(builder.Configuration) (extension in SatelliteProvider.Api.Authentication) registers JwtBearer with TokenValidationParameters set per the suite auth contract (signature + lifetime, no issuer/audience validation, 30 s clock skew, ≥ 32-byte HMAC key). Followed by AddAuthorization().

Startup

1. Database migration via DatabaseMigrator.RunMigrations() — throws on failure
2. Creates tiles and ready directories
3. Swagger enabled in Development mode
4. Middleware chain (order matters): UseExceptionHandler → UseHttpsRedirection → UseCors("TilesCors") → UseAuthentication → UseAuthorization → endpoint mapping.
5. Every MapGet/MapPost endpoint is decorated with .RequireAuthorization(); the framework returns 401 before the handler runs for any anonymous, expired, or invalid-signature request.

ServeTile Handler

1. Checks IMemoryCache for tile bytes (1h absolute, 30min sliding expiration)
2. If cache miss: queries ITileRepository.GetByTileCoordinatesAsync
3. If no DB record: downloads tile via GoogleMapsDownloaderV2.DownloadSingleTileAsync, creates TileEntity, inserts
4. Returns image bytes with cache headers (Cache-Control: public, max-age=86400)

GetTileByLatLon Handler

Downloads a tile, persists it, returns metadata as DownloadTileResponse.

RequestRegion Handler

Validates size (100–10000m), delegates to IRegionService.RequestRegionAsync.

Dependencies

All project references: Common, DataAccess, Services. NuGet: Serilog.AspNetCore, Swashbuckle.AspNetCore, Microsoft.AspNetCore.OpenApi, Microsoft.AspNetCore.Authentication.JwtBearer (8.0.21, AZ-487), SixLabors.ImageSharp, Newtonsoft.Json.

Consumers

• HTTP clients (external)
• Integration tests (via HTTP)

Data Models

Defines several local request/response records that are not shared with other projects.

Configuration

All configuration sections are consumed here:

• ConnectionStrings:DefaultConnection
• MapConfig, StorageConfig, ProcessingConfig
• CorsConfig:AllowedOrigins
• Jwt:Secret — HMAC-SHA256 signing key for JWT validation (AZ-487). Resolution: JWT_SECRET env var (preferred, opaque production secret) → Jwt:Secret configuration key (appsettings.Development.json placeholder only). Startup fails fast if the resolved value is unset, empty, or shorter than 32 bytes.
• Serilog section

External Integrations

• Google Maps (indirectly via GoogleMapsDownloaderV2)
• PostgreSQL (via repositories and DatabaseMigrator)
• File system (./tiles/, ./ready/)

Security

• CORS configured (permissive by default when no origins specified)
• Swagger only in Development; Bearer token "Authorize" button registered via AddSecurityDefinition/AddSecurityRequirement (AZ-487)
• HTTPS redirection enabled
• JWT bearer authentication (AZ-487) — every endpoint requires a valid HS256-signed token. Anonymous, expired, or signature-tampered requests return 401 before the handler runs. Per-endpoint permission claims are layered on top in subsequent PBIs (e.g. AZ-488 requires permissions: ["GPS"] on the upload endpoint).

Tests

Integration tests exercise all endpoints. Unit test project has only a dummy test.