# Module Layout

**Status**: derived-from-code

**Language**: csharp
**Layout Convention**: custom (per-component .csproj per logical component)
**Root**: ./
**Last Updated**: 2026-05-11 (post AZ-350 03-code-quality-refactoring run; corrects DataAccess→Common dependency)

## 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()`).

## 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/DTO/*.cs` (all DTOs)
  - `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`
- **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`
  - `SatelliteProvider.DataAccess/Repositories/IRegionRepository.cs`
  - `SatelliteProvider.DataAccess/Repositories/IRouteRepository.cs`
  - `SatelliteProvider.DataAccess/Repositories/TileRepository.cs`
  - `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` (5 sites: `RegionRepository`, `IRegionRepository`, `Models/RegionEntity`, `Models/RoutePointEntity`, `TypeHandlers/EnumStringTypeHandler`); `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/TileDownloaderServiceCollectionExtensions.cs` (DI: `AddTileDownloader()`)
- **Internal**: (none)
- **Owns**: `SatelliteProvider.Services.TileDownloader/**`
- **ProjectReferences**: `SatelliteProvider.Common`, `SatelliteProvider.DataAccess`
- **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)
- **Internal**: (none)
- **Owns**: `SatelliteProvider.Api/**`
- **Imports from**: Common, DataAccess, TileDownloader, 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 geospatial utility functions (coordinate math, distance, bearing)
- **Consumed by**: TileDownloader, RegionProcessing, RouteManagement

## 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`.