azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 17:21:13 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
d327000fb6d0346c1f572e0506c363c778ebae20
satellite-provider/_docs/02_document/module-layout.md
T
Oleksandr Bezdieniezhnykh 6b373082c8 [AZ-315] Sync architecture docs after coupling refactor 
Phase C of architecture coupling refactor (epic AZ-309). Closes the
last baseline finding (F5 — DataAccess incorrectly documented as
importing Common) and synchronizes the rest of _docs/02_document/
with the post-split project layout from AZ-312/313/314:

- module-layout.md: per-component sections for the three new csprojs
  with explicit ProjectReferences and the no-cross-sibling-reference
  invariant the split enforces.
- architecture.md: components and internal-communication tables
  updated to show calls flow through Common interfaces.
- architecture_compliance_baseline.md: F1..F5 marked Resolved with
  task IDs and commit refs; baseline summary now 0 findings.
- diagrams/components.md, components/03_tile_downloader/description.md,
  modules/{common_interfaces,services_tile_service,
  services_google_maps_downloader,tests_unit}.md updated for the
  split, RateLimitException relocation, and new ITileService methods.

Documentation-only batch — no code, no tests, no build changes.
Epic AZ-309 complete (6 tasks across 3 batches).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-10 07:25:21 +03:00

153 lines
8.6 KiB
Markdown
Raw Blame History

# Module Layout
**Status**: derived-from-code
**Language**: csharp
**Layout Convention**: custom (per-component .csproj per logical component)
**Root**: ./
**Last Updated**: 2026-05-10 (post AZ-309 coupling refactor)
## 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/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/**`
- **Imports from**: (none — fully self-contained, no project references)
- **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, DataAccess | Common: (none); DataAccess: (none) |
**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. An alternative layering could place it at Layer 2, but the current code treats repositories as infrastructure, not domain logic.
- **DataAccess has no ProjectReference to Common**: confirmed by inspecting `SatelliteProvider.DataAccess.csproj`. DataAccess models and repositories are self-contained (do not use any types from Common). This contradicts an earlier baseline assumption (compliance baseline F5).
Reference in New Issue View Git Blame Copy Permalink