satellite-provider/_docs/02_document/components/02_data_access/description.md

DataAccess (Persistence)

1. High-Level Overview

Purpose: Database persistence layer providing Dapper-based repositories for tiles, regions, routes, and route points, plus DbUp-driven schema migrations.

Architectural Pattern: Repository pattern with raw SQL (Dapper)

Upstream dependencies: None at project level (uses Microsoft.Extensions abstractions from NuGet)

Downstream consumers: TileDownloader (TileRepository), RegionProcessing (RegionRepository), RouteManagement (RouteRepository, RegionRepository), WebApi (TileRepository for ServeTile)

2. Internal Interfaces

Interface: ITileRepository

Method	Input	Output	Async	Error Types
GetByIdAsync	Guid	TileEntity?	Yes	NpgsqlException
GetByTileCoordinatesAsync	zoom, x, y	TileEntity? (most-recent across sources, AZ-484)	Yes	NpgsqlException
GetTilesByRegionAsync	lat, lon, sizeM, zoom	IEnumerable<TileEntity> (one row per cell via DISTINCT ON, AZ-484)	Yes	NpgsqlException
InsertAsync	TileEntity	Guid (per-source UPSERT, AZ-484)	Yes	NpgsqlException
UpdateAsync	TileEntity	int	Yes	NpgsqlException
DeleteAsync	Guid	int	Yes	NpgsqlException

FindExistingTileAsync was removed by AZ-376 (replaced by direct cell lookups through GetByTileCoordinatesAsync + GetTilesByRegionAsync).

Interface: IRegionRepository

Method	Input	Output	Async	Error Types
GetByIdAsync	Guid	RegionEntity?	Yes	NpgsqlException
GetByStatusAsync	string	IEnumerable<RegionEntity>	Yes	NpgsqlException
InsertAsync	RegionEntity	Guid	Yes	NpgsqlException
UpdateAsync	RegionEntity	int	Yes	NpgsqlException
DeleteAsync	Guid	int	Yes	NpgsqlException

Interface: IRouteRepository

Method	Input	Output	Async	Error Types
GetByIdAsync	Guid	RouteEntity?	Yes	NpgsqlException
GetRoutePointsAsync	Guid routeId	IEnumerable<RoutePointEntity>	Yes	NpgsqlException
InsertRouteAsync	RouteEntity	Guid	Yes	NpgsqlException
InsertRoutePointsAsync	IEnumerable<RoutePointEntity>	void	Yes	NpgsqlException
UpdateRouteAsync	RouteEntity	int	Yes	NpgsqlException
LinkRouteToRegionAsync	routeId, regionId, isGeofence, polygonIndex	void	Yes	NpgsqlException
GetRegionIdsByRouteAsync	Guid routeId	IEnumerable<Guid>	Yes	NpgsqlException
GetGeofenceRegionIdsByRouteAsync	Guid routeId	IEnumerable<Guid>	Yes	NpgsqlException
GetGeofenceRegionsByPolygonAsync	Guid routeId	Dictionary<int, List<Guid>>	Yes	NpgsqlException
GetRoutesWithPendingMapsAsync	—	IEnumerable<RouteEntity>	Yes	NpgsqlException

Class: DatabaseMigrator

Method	Input	Output	Async	Error Types
RunMigrations	—	bool	No	Exception

4. Data Access Patterns

Queries

Query	Frequency	Hot Path	Index Needed
GetByTileCoordinatesAsync (tile lookup)	Very High	Yes	(tile_zoom, tile_x, tile_y)
GetTilesByRegionAsync (spatial)	High	Yes	(latitude, longitude, tile_zoom)
InsertAsync (tile per-source upsert)	High	Yes	Composite unique on (tile_zoom, tile_x, tile_y, tile_size_meters, source, COALESCE(flight_id, '00000000-0000-0000-0000-000000000000'::uuid)) (AZ-503: idx_tiles_unique_identity; supersedes the AZ-484 float-based idx_tiles_unique_location_source)
GetByStatusAsync (region polling)	Medium	No	(status)
GetRoutesWithPendingMapsAsync	Low	No	(request_maps, maps_ready)

Storage Estimates

Table	Est. Row Count (1yr)	Row Size	Growth Rate
tiles	~100K–1M (depends on usage)	~200B	Variable
regions	~10K–50K	~150B	Proportional to tile requests
routes	~1K–5K	~200B	Low
route_points	~50K–500K	~100B	Proportional to routes
route_regions	~10K–100K	~50B	Proportional to routes

5. Implementation Details

State Management: Stateless — each repository creates a new Npgsql connection per method call. Npgsql handles internal connection pooling.

Key Dependencies:

Library	Version	Purpose
Dapper	2.1.35	Micro-ORM for SQL queries
Npgsql	9.0.2	PostgreSQL ADO.NET driver
dbup-postgresql	6.0.3	Schema migration runner

Error Handling: Exceptions propagate to callers. No retry logic at the repository level.

7. Caveats & Edge Cases

• Repository interfaces are defined in this project (not in Common), creating a dependency from Services to DataAccess
• Column mapping uses SQL aliases (tile_zoom as TileZoom) rather than Dapper attribute mapping
• TileRepository.InsertAsync uses an integer-only, flight-aware UPSERT pattern (AZ-503; supersedes the AZ-484 5-column float-based UPSERT). Same-source same-flight re-inserts overwrite and refresh captured_at/location_hash/content_sha256; different sources or different flights at the same cell coexist as separate rows. id is intentionally NOT overwritten on conflict so it stays deterministic per AZ-503 AC-2.
• TileEntity.Source is stored as a plain string (not the TileSource enum) due to Dapper issue #259 — see _docs/LESSONS.md L-001. Conversion happens via SatelliteProvider.Common.Enums.TileSourceConverter
• AZ-503 deterministic identity: id is Uuidv5(TileNamespace, "{z}/{x}/{y}/{source}/{flight_id or zero-uuid}") and location_hash is Uuidv5(TileNamespace, "{z}/{x}/{y}"). The cross-repo TileNamespace constant lives in SatelliteProvider.Common.Utils.Uuidv5 and MUST match gps-denied-onboard/components/c6_tile_cache/_uuid.py:TILE_NAMESPACE.
• The frozen v1.0.0 tile-storage contract (_docs/02_document/contracts/data-access/) is the AZ-484-era spec for read-side selection invariants; the AZ-503 write-side schema change is documented inline in dataaccess_models.md and dataaccess_tile_repository.md. A v2.0.0 contract bump is deferred to AZ-505 (when the POST /api/satellite/tiles/inventory endpoint freezes the new identity surface for external consumers).
• No soft-delete; DeleteAsync is a hard delete

8. Dependency Graph

Must be implemented after: nothing (parallel with Common) Can be implemented in parallel with: Common Blocks: TileDownloader, RegionProcessing, RouteManagement, WebApi

9. Logging Strategy

Log Level	When	Example
INFO	Migration start/complete	Starting database migrations...
ERROR	Migration failure	Database migration failed

Structured logging via ILogger<T>. Logger injected but rarely used in repositories.