azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 09:31:13 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
e9d6db077cbfdc6f8a37cff0a2b78cc9c95879b6
satellite-provider/_docs/02_document/module-layout.md
T
Oleksandr Bezdieniezhnykh e9d6db077c [AZ-484] Fix multi-source tile reads: drop Dapper enum handler 
Two integration-test failures uncovered after the initial commit:

1) GetTilesByRegionAsync outer ORDER BY referenced 'updated_at' but
   the inner DISTINCT ON subquery aliased it to 'UpdatedAt' (Postgres
   folds to 'updatedat'). DISTINCT ON already guarantees one row per
   (latitude, longitude, ...) so the third tiebreak was unreachable;
   removed it.

2) Dapper 2.1.35 silently bypasses SqlMapper.TypeHandler<T> for enum
   types during read deserialization (Dapper issue #259). The
   TileSourceTypeHandler worked for writes but reads fell through to
   Enum.TryParse, which cannot map 'google_maps' to GoogleMaps.

   Pivoted: TileEntity.Source is now a string (the wire value).
   TileSource enum stays as the public producer surface in
   Common.Enums; TileSourceConverter (Common.Enums) provides
   ToWireValue / FromWireValue / IsValidWireValue at the boundary.
   TileSourceTypeHandler deleted; registration removed from
   DapperEnumTypeHandlers.RegisterAll.

   tile-storage.md Inv-5 amended to document the storage choice.
   _docs/LESSONS.md L-001 records the Dapper bypass for future cycles.

Full suite passes (213 unit + integration suite incl. AZ-484
AC-1..AC-5, security SEC-01..SEC-04, AZ-356/362/357).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 06:44:34 +03:00

9.7 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-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.
Reference in New Issue View Git Blame Copy Permalink