satellite-provider/_docs/02_document/module-layout.md

Module Layout

Status: derived-from-code

Language: csharp Layout Convention: custom (per-component .csproj per logical component) Root: ./ Last Updated: 2026-05-12 (cycle 6 — AZ-505 tile inventory + Leaflet covering index + HTTP/2: new POST /api/satellite/tiles/inventory endpoint, new ITileRepository.GetTilesByLocationHashesAsync, rewired GetByTileCoordinatesAsync to filter on location_hash, migration 015_AddTilesLeafletPathIndex.sql, Kestrel Http1AndHttp2, new TileInventory* DTOs in Common; cycle 5 — AZ-503 tile-identity foundation added: SatelliteProvider.Common/Utils/Uuidv5.cs, migration 014_AddTileIdentityColumns.sql, 4 new TileEntity columns, integer-only flight-aware UPSERT, IntegrationTests → Common ProjectReference)

Layout Rules

1. Each component owns ONE top-level project directory (.csproj boundary). The previous shared SatelliteProvider.Services project was split into three per-component csprojs in epic AZ-309.
2. Shared code lives under SatelliteProvider.Common/ — the foundation layer.
3. Cross-cutting concerns (DTOs, interfaces, configs, geo-math, common exceptions) all reside in Common.
4. Public API surface per component = public types in the namespace root. Everything marked internal or private is internal.
5. Tests live in separate projects: SatelliteProvider.Tests/ (unit) and SatelliteProvider.IntegrationTests/ (integration).
6. DI registration per component lives in a <Component>ServiceCollectionExtensions.cs adjacent to the component's classes (e.g. TileDownloaderServiceCollectionExtensions.AddTileDownloader()).

Documentation Layout (canonical — AZ-495)

Each Layer-3 service component (Common, DataAccess, TileDownloader, RegionProcessing, RouteManagement) owns one description file under _docs/02_document/components/0N_<name>/description.md. The numeric prefix (01_common ... 05_route_management) matches the architectural-layer order — not the alphabetical order.

The WebApi component (SatelliteProvider.Api) intentionally does NOT have a components/* folder. Its documentation lives in _docs/02_document/modules/api_program.md. The rationale is that WebApi is the orchestrator / entry-point at Layer 4 rather than a Layer-3 service component — its concerns are minimal-API endpoint mapping, DI composition, and middleware chain composition, all of which are documented at module-level alongside the other process-level concerns (tests_unit.md, tests_integration.md, migrations.md). Splitting WebApi documentation into a component-stub plus a module file would create two sources of truth.

When authoring or reading a task that touches WebApi, use _docs/02_document/modules/api_program.md as the documentation anchor. Task-spec templates and the new-task / decompose skills point at this path; the components/06_web_api/ folder is intentionally absent and MUST NOT be created.

The cycle-1 (AZ-487) and cycle-2 (AZ-488) code reviews each surfaced an F1 (Low / Style) finding because task specs referenced the non-existent components/01_web_api/description.md path. AZ-495 settles this convention; the finding should not recur.

Per-Component Mapping

Component: Common

• Directory: SatelliteProvider.Common/
• Public API:
  • SatelliteProvider.Common/Configs/MapConfig.cs
  • SatelliteProvider.Common/Configs/StorageConfig.cs
  • SatelliteProvider.Common/Configs/ProcessingConfig.cs
  • SatelliteProvider.Common/Configs/DatabaseConfig.cs
  • SatelliteProvider.Common/Configs/UavQualityConfig.cs (added by AZ-488; UAV quality-gate + request-envelope knobs)
  • SatelliteProvider.Common/DTO/*.cs (all DTOs; AZ-488 added UavTileMetadata, UavTileBatchMetadataPayload, UavTileBatchUploadResponse, UavTileUploadResultItem, UavTileUploadStatus, UavTileRejectReasons — placed in Common to keep TileDownloader from depending on the API layer; AZ-505 added TileInventory.cs housing TileInventoryRequest, TileCoord, TileInventoryResponse, TileInventoryEntry, TileInventoryLimits for the bulk-lookup endpoint)
  • SatelliteProvider.Common/Enums/RegionStatus.cs
  • SatelliteProvider.Common/Enums/RoutePointType.cs
  • SatelliteProvider.Common/Enums/TileSource.cs (added by AZ-484; backed by the tile-storage v1.0.0 contract)
  • SatelliteProvider.Common/Enums/TileSourceConverter.cs (added by AZ-484; converts TileSource enum to/from the snake_case wire string used by TileEntity.Source)
  • SatelliteProvider.Common/Exceptions/RateLimitException.cs
  • SatelliteProvider.Common/Interfaces/*.cs (all service interfaces)
  • SatelliteProvider.Common/Utils/GeoUtils.cs
  • SatelliteProvider.Common/Utils/Uuidv5.cs (added by AZ-503; deterministic UUIDv5 generator + cross-repo TileNamespace constant pinned to 5b8d0c2e-7f1a-4d3b-9c5e-1f3a8e7d2b6c)
• Internal: (none — all types are public, shared across components)
• Owns: SatelliteProvider.Common/**
• Imports from: (none)
• Consumed by: DataAccess, TileDownloader, RegionProcessing, RouteManagement, WebApi

Component: DataAccess

• Directory: SatelliteProvider.DataAccess/
• Public API:
  • SatelliteProvider.DataAccess/Models/TileEntity.cs
  • SatelliteProvider.DataAccess/Models/RegionEntity.cs
  • SatelliteProvider.DataAccess/Models/RouteEntity.cs
  • SatelliteProvider.DataAccess/Models/RoutePointEntity.cs
  • SatelliteProvider.DataAccess/Repositories/ITileRepository.cs (AZ-505 added GetTilesByLocationHashesAsync for the bulk inventory hot path)
  • SatelliteProvider.DataAccess/Repositories/IRegionRepository.cs
  • SatelliteProvider.DataAccess/Repositories/IRouteRepository.cs
  • SatelliteProvider.DataAccess/Repositories/TileRepository.cs (AZ-505 rewired GetByTileCoordinatesAsync to filter on location_hash for Index Only Scan against tiles_leaflet_path; added Npgsql-direct GetTilesByLocationHashesAsync to sidestep Dapper's IEnumerable parameter expansion against ANY($1::uuid[]))
  • SatelliteProvider.DataAccess/Repositories/RegionRepository.cs
  • SatelliteProvider.DataAccess/Repositories/RouteRepository.cs
  • SatelliteProvider.DataAccess/DatabaseMigrator.cs
• Internal: (none — all repository types are public for DI registration)
• Owns: SatelliteProvider.DataAccess/**
• ProjectReferences: SatelliteProvider.Common
• Imports from: SatelliteProvider.Common.Enums (6 sites: RegionRepository, IRegionRepository, Models/RegionEntity, Models/RoutePointEntity, TypeHandlers/EnumStringTypeHandler, Models/TileEntity — references TileSourceConverter.GoogleMapsWireValue const for the AZ-484 default value); SatelliteProvider.Common.Configs (MapConfig.DefaultTileSizePixels in TileRepository); SatelliteProvider.Common.Utils (GeoUtils.EarthEquatorialCircumferenceMeters, GeoUtils.MetersPerDegreeLatitude in TileRepository).
• Consumed by: TileDownloader, RegionProcessing, RouteManagement, WebApi

Component: TileDownloader

• Directory: SatelliteProvider.Services.TileDownloader/
• csproj: SatelliteProvider.Services.TileDownloader/SatelliteProvider.Services.TileDownloader.csproj
• Public API:
  • SatelliteProvider.Services.TileDownloader/GoogleMapsDownloaderV2.cs (implements ISatelliteDownloader)
  • SatelliteProvider.Services.TileDownloader/TileService.cs (implements ITileService)
  • SatelliteProvider.Services.TileDownloader/UavTileQualityGate.cs + IUavTileQualityGate (added by AZ-488; 5-rule synchronous validator over ReadOnlyMemory<byte> JPEGs, uses SixLabors.ImageSharp 3.1.11 + TimeProvider)
  • SatelliteProvider.Services.TileDownloader/UavTileUploadHandler.cs + IUavTileUploadHandler (added by AZ-488; orchestrates batch validation → file-first persistence → ITileRepository.InsertAsync UPSERT; owns the UAV ./tiles/uav/{z}/{x}/{y}.jpg path layout)
  • SatelliteProvider.Services.TileDownloader/TileDownloaderServiceCollectionExtensions.cs (DI: AddTileDownloader() — also registers the AZ-488 quality gate and upload handler as singletons)
• Internal: (none)
• Owns: SatelliteProvider.Services.TileDownloader/**
• ProjectReferences: SatelliteProvider.Common, SatelliteProvider.DataAccess
• PackageReferences (added by AZ-488): SixLabors.ImageSharp 3.1.11 (image identify / L8 decode / downsample for the variance heuristic).
• Imports from: Common, DataAccess
• Consumed by: RegionProcessing (via ITileService from Common; no direct ProjectReference), WebApi

Component: RegionProcessing

• Directory: SatelliteProvider.Services.RegionProcessing/
• csproj: SatelliteProvider.Services.RegionProcessing/SatelliteProvider.Services.RegionProcessing.csproj
• Public API:
  • SatelliteProvider.Services.RegionProcessing/RegionService.cs (implements IRegionService)
  • SatelliteProvider.Services.RegionProcessing/RegionProcessingService.cs (background hosted service)
  • SatelliteProvider.Services.RegionProcessing/RegionRequestQueue.cs (implements IRegionRequestQueue)
  • SatelliteProvider.Services.RegionProcessing/RegionProcessingServiceCollectionExtensions.cs (DI: AddRegionProcessing())
• Internal: (none)
• Owns: SatelliteProvider.Services.RegionProcessing/**
• ProjectReferences: SatelliteProvider.Common, SatelliteProvider.DataAccess
• Imports from: Common, DataAccess (uses ITileService from Common — no compile-time dependency on TileDownloader)
• Consumed by: RouteManagement (via IRegionService and IRegionRequestQueue from Common; no direct ProjectReference), WebApi

Component: RouteManagement

• Directory: SatelliteProvider.Services.RouteManagement/
• csproj: SatelliteProvider.Services.RouteManagement/SatelliteProvider.Services.RouteManagement.csproj
• Public API:
  • SatelliteProvider.Services.RouteManagement/RouteService.cs (implements IRouteService)
  • SatelliteProvider.Services.RouteManagement/RouteProcessingService.cs (background hosted service)
  • SatelliteProvider.Services.RouteManagement/RouteManagementServiceCollectionExtensions.cs (DI: AddRouteManagement())
• Internal: (none)
• Owns: SatelliteProvider.Services.RouteManagement/**
• ProjectReferences: SatelliteProvider.Common, SatelliteProvider.DataAccess
• Imports from: Common, DataAccess (uses IRegionService / IRegionRequestQueue from Common — no compile-time dependency on RegionProcessing)
• Consumed by: WebApi

Component: WebApi

• Directory: SatelliteProvider.Api/
• Public API:
  • SatelliteProvider.Api/Program.cs (minimal API endpoints, DI setup, middleware chain — UseAuthentication + UseAuthorization added in AZ-487; /api/satellite/upload rewired in AZ-488; AZ-505 added POST /api/satellite/tiles/inventory + builder.WebHost.ConfigureKestrel(... Protocols = HttpProtocols.Http1AndHttp2) for HTTP/2 via TLS + ALPN on the dev https://+:8080 listener; cert is generated by scripts/run-tests.sh into ./certs/api.pfx and bound through ASPNETCORE_Kestrel__Certificates__Default__Path)
  • SatelliteProvider.Api/Authentication/AuthenticationServiceCollectionExtensions.cs (added by AZ-487; AddSatelliteJwt(IConfiguration) registers JwtBearer with the suite-wide HS256 contract from suite/_docs/10_auth.md; validates JWT_SECRET ≥ 32 bytes at startup)
  • SatelliteProvider.Api/Authentication/PermissionsRequirement.cs + PermissionsAuthorizationHandler + SatellitePermissions (added by AZ-488; custom requirement that accepts a permissions claim shaped as either a single string or a JSON array; powers the UavUploadPolicy requiring the GPS permission)
  • SatelliteProvider.Api/DTOs/UavTileBatchUploadRequest.cs (added by AZ-488; multipart form binding envelope — kept in WebApi because it depends on IFormFileCollection + [FromForm], both API-layer types)
  • SatelliteProvider.Api/Validators/ValidationEndpointFilter.cs + ValidationEndpointFilterExtensions.cs (added by AZ-795; generic IEndpointFilter<T> that runs the registered IValidator<T> and returns Results.ValidationProblem on failure; opt-in via RouteHandlerBuilder.WithValidation<T>())
  • SatelliteProvider.Api/Validators/InventoryRequestValidator.cs + TileCoordValidator (added by AZ-796; FluentValidation rules for POST /api/satellite/tiles/inventory — XOR tiles/locationHashes, per-array cap, slippy-map range checks)
  • SatelliteProvider.Api/Validators/GlobalValidatorConfig.cs (added by AZ-795/AZ-796; idempotent ApplyOnce() configures ValidatorOptions.Global.PropertyNameResolver so errors-map keys are camelCase per error-shape.md Inv-4; called from Program.cs and from the test assembly's ModuleInitializer)
• Internal: (none)
• Owns: SatelliteProvider.Api/**
• PackageReferences (added by AZ-487, bumped by AZ-496, then by AZ-500; AZ-795 added FluentValidation): Microsoft.AspNetCore.Authentication.JwtBearer 10.0.7 (pinned to the same minor patch as Microsoft.AspNetCore.OpenApi 10.0.7; AZ-496 bumped both packages from 8.0.21 → 8.0.25 in cycle 3 to close cycle-1 D1 + cycle-2 D3 supply-chain findings, then AZ-500 bumped both 8.0.25 → 10.0.7 in cycle 4 as part of the .NET 8 → .NET 10 migration; AZ-500 also bumped Swashbuckle.AspNetCore 6.6.2 → 10.1.7 here to land Microsoft.OpenApi 2.x compat required by ASP.NET Core 10). FluentValidation + FluentValidation.DependencyInjectionExtensions 12.0.0 added by AZ-795 to back the strict-input-validation epic.
• Imports from: Common (incl. AZ-488 UAV DTOs + UavQualityConfig), DataAccess, TileDownloader (incl. AZ-488 IUavTileUploadHandler), RegionProcessing, RouteManagement
• Consumed by: (none — top-level entry point)

Shared / Cross-Cutting

Common/Configs

• Directory: SatelliteProvider.Common/Configs/
• Purpose: Strongly-typed configuration POCOs bound via IOptions<T>
• Consumed by: all components

Common/DTO

• Directory: SatelliteProvider.Common/DTO/
• Purpose: Data transfer objects shared across layers (request/response models, value types)
• Consumed by: all components

Common/Interfaces

• Directory: SatelliteProvider.Common/Interfaces/
• Purpose: Service contracts enabling DI and testability
• Consumed by: all components (services implement, API and consumers depend on)

Common/Utils

• Directory: SatelliteProvider.Common/Utils/
• Purpose: Stateless utility functions — geospatial (GeoUtils: coordinate math, distance, bearing) and identity (Uuidv5: deterministic UUIDv5 generator + cross-repo TileNamespace constant, added by AZ-503).
• Consumed by: TileDownloader, RegionProcessing, RouteManagement, IntegrationTests (AZ-503 added a ProjectReference from SatelliteProvider.IntegrationTests to SatelliteProvider.Common so test seeders can call Uuidv5.Create directly instead of duplicating the algorithm)

Common/Enums

• Directory: SatelliteProvider.Common/Enums/
• Purpose: Domain enums shared across layers (RegionStatus, RoutePointType, TileSource) plus their explicit wire-value converters when persistence requires snake_case strings (TileSourceConverter). Converter classes belong here — not in DataAccess — because they encode a domain-level vocabulary that must be visible to every component.
• Consumed by: DataAccess (entity defaults, type handler registration), TileDownloader (sets TileEntity.Source via TileSourceConverter.ToWireValue), Tests
• Important constraint: Dapper's SqlMapper.TypeHandler<TEnum> is bypassed for enum reads (Dapper issue #259 — see _docs/LESSONS.md L-001). For any new enum that must round-trip through a database column, prefer the string-on-entity + Enum-at-API-boundary pattern with a converter class in this folder. Do NOT register a TypeHandler<TEnum> and assume it will be honored on reads.

TestSupport (added by AZ-491; extended by AZ-493)

• Directory: SatelliteProvider.TestSupport/
• csproj: SatelliteProvider.TestSupport/SatelliteProvider.TestSupport.csproj (class library, no test framework)
• Purpose: Canonical home for cross-project test utilities. Currently holds JwtTokenFactory (HS256 token minting + signature tampering) and IntegrationTestResetGuard (pure-string guard for the integration-test DB-reset hook). Replaces the cycle-2 duplicate that lived in both SatelliteProvider.Tests/TestUtilities/JwtTokenFactory.cs and SatelliteProvider.IntegrationTests/JwtTestHelpers.cs and required parallel fixes. Future additions: shared image-fixture factories, shared deterministic clocks / test-data builders that need to be visible to both unit and integration projects.
• Public API:
  • SatelliteProvider.TestSupport/JwtTokenFactory.cs (Create, CreateExpired, TamperSignature) — added by AZ-491.
  • SatelliteProvider.TestSupport/IntegrationTestResetGuard.cs (EnsureGuardPassesOrThrow, AllowedHosts, EnvironmentEnvVar, TestingEnvironment) — added by AZ-493. Pure static class — no I/O, no DB calls. Consumed by SatelliteProvider.IntegrationTests/IntegrationTestDatabaseReset.cs (instance class that owns the Npgsql side effects) and unit-tested in SatelliteProvider.Tests/TestSupport/IntegrationTestResetGuardTests.cs.
• PackageReferences: Microsoft.IdentityModel.Tokens 7.0.3, System.IdentityModel.Tokens.Jwt 7.0.3 (matches the integration tests' pre-AZ-491 explicit reference). The AZ-493 guard introduced no new package dependencies — it is pure string comparison over the BCL.
• Consumed by: SatelliteProvider.Tests, SatelliteProvider.IntegrationTests (both via ProjectReference).
• Not consumed by: production projects (Api, Common, DataAccess, Services.*). The TestSupport library is test-only by design; production code must NOT depend on it.
• Runner-side concerns NOT in TestSupport: SatelliteProvider.IntegrationTests/JwtTestHelpers.cs retains ResolveSecretOrThrow, AttachDefaultAuthorization, and the DefaultSubject = "integration-tests" constant — these are runner-specific (env-var reads, HttpClient mutation, runner-identity subject) and intentionally not consolidated. SatelliteProvider.IntegrationTests/IntegrationTestDatabaseReset.cs (AZ-493) holds the Npgsql side effects of the reset — it sits in the integration-tests project (not TestSupport) so the Npgsql dependency doesn't leak into unit tests. SatelliteProvider.IntegrationTests/PerfBootstrap.cs (AZ-492) holds the --mint-only / --gen-uav-fixture subcommands consumed by scripts/run-performance-tests.sh; it sits in IntegrationTests (not TestSupport) so the SixLabors.ImageSharp dependency stays out of unit tests, while the token-mint surface delegates to SatelliteProvider.TestSupport.JwtTokenFactory.Create — no third copy of the JWT logic.

Allowed Dependencies (layering)

Layer	Components	May import from (compile-time ProjectReferences)
4. API / Entry	WebApi	Common, DataAccess, TileDownloader, RegionProcessing, RouteManagement
3. Application	TileDownloader, RegionProcessing, RouteManagement	Common, DataAccess only — siblings communicate through interfaces in Common, never through direct ProjectReferences
1. Foundation	Common (leaf-most), DataAccess	Common: (none); DataAccess: Common only — Common MUST NOT import from DataAccess

Key constraint enforced by the AZ-309 split: the three Layer-3 components are compile-time siblings. Any cross-sibling call (e.g. RegionProcessing invoking tile download) MUST go through an interface defined in SatelliteProvider.Common.Interfaces and resolved via DI — adding a ProjectReference between siblings is now structurally impossible without re-introducing the coupling the refactor removed.

Verification

• No detected cycles: The dependency graph is a clean DAG.
• No cross-sibling ProjectReferences: TileDownloader, RegionProcessing, and RouteManagement each reference only Common + DataAccess. Verified by inspecting all three csproj files.
• DataAccess layer placement: DataAccess sits at Layer 1 (Foundation) alongside Common because it is consumed uniformly by all service components. It is one half-step above Common because it depends on Common for shared enums and a small number of constants/configs.
• DataAccess→Common ProjectReference: confirmed present in SatelliteProvider.DataAccess.csproj line 18 and used by 7 source sites (5 enum imports, 1 MapConfig.DefaultTileSizePixels site, 1 GeoUtils.* site). The earlier compliance baseline F5 entry that claimed "DataAccess has no Common dependency" was inaccurate — both module-layout.md and architecture_compliance_baseline.md were corrected during the 03-code-quality-refactoring run (2026-05-11). The actual constraint that holds is one-way: Common MUST NOT import from DataAccess.