azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 14:11:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
4c88201e5c79b192cde755aa894e623df4be20bb
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

8.6 KiB
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