mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-21 22:41:14 +00:00
Oleksandr Bezdieniezhnykh
23ab05766d
Replaces bare strings with two enums in Common/Enums/:
RegionStatus { Queued, Processing, Completed, Failed }
RoutePointType { Start, End, Action, Intermediate }
Adds a Dapper EnumStringTypeHandler<T> (DataAccess/TypeHandlers/)
that round-trips enums to/from lowercase strings, registered once
at startup via DapperEnumTypeHandlers.RegisterAll(). DataAccess now
references Common (project ref) so entities can carry the enum types.
Sites converted: RegionService (5), RouteProcessingService (3),
RoutePointGraphBuilder (4), entity Status/PointType columns. Log
message and summary file format preserved via .ToLowerInvariant().
API JSON contract preserved by adding JsonStringEnumConverter with
JsonNamingPolicy.CamelCase to the http JSON options — single-word
enum members serialize to the same lowercase strings as before.
DTO renamed: Common.DTO.RegionStatus -> RegionStatusResponse to
free the RegionStatus name for the new enum (forced by the task's
explicit enum name); the renamed DTO has no public-API impact at
the JSON wire level. Stale doc references updated.
AC RT2 in _docs/00_problem/acceptance_criteria.md now lists all 4
point types (start/end/action/intermediate).
Tests: 171 / 171 unit + 5 / 5 smoke green (was 141 + 5; +30 new tests
covering type handler round-trip, set/parse, unknown-value rejection,
idempotent registration, and the AC RT2 doc check).
Co-authored-by: Cursor <cursoragent@cursor.com>
209 lines
8.2 KiB
Markdown
209 lines
8.2 KiB
Markdown
# Codebase Discovery
|
|
|
|
## Directory Tree
|
|
|
|
```
|
|
satellite-provider/
|
|
├── SatelliteProvider.sln
|
|
├── global.json
|
|
├── docker-compose.yml
|
|
├── docker-compose.tests.yml
|
|
├── goal.md
|
|
├── README.md
|
|
├── AGENTS.md
|
|
├── .woodpecker/
|
|
│ ├── 01-test.yml
|
|
│ └── 02-build-push.yml
|
|
├── SatelliteProvider.Api/
|
|
│ ├── Dockerfile
|
|
│ ├── Program.cs
|
|
│ ├── SatelliteProvider.Api.csproj
|
|
│ ├── Properties/launchSettings.json
|
|
│ ├── appsettings.json
|
|
│ └── appsettings.Development.json
|
|
├── SatelliteProvider.Common/
|
|
│ ├── SatelliteProvider.Common.csproj
|
|
│ ├── Configs/
|
|
│ │ ├── DatabaseConfig.cs
|
|
│ │ ├── MapConfig.cs
|
|
│ │ ├── ProcessingConfig.cs
|
|
│ │ └── StorageConfig.cs
|
|
│ ├── DTO/
|
|
│ │ ├── CreateRouteRequest.cs
|
|
│ │ ├── Direction.cs
|
|
│ │ ├── GeoPoint.cs
|
|
│ │ ├── GeofencePolygon.cs
|
|
│ │ ├── RegionRequest.cs
|
|
│ │ ├── RegionStatusResponse.cs
|
|
│ │ ├── RoutePoint.cs
|
|
│ │ ├── RoutePointDto.cs
|
|
│ │ ├── RouteResponse.cs
|
|
│ │ ├── SatTile.cs
|
|
│ │ └── TileMetadata.cs
|
|
│ ├── Interfaces/
|
|
│ │ ├── IRegionRequestQueue.cs
|
|
│ │ ├── IRegionService.cs
|
|
│ │ ├── IRouteService.cs
|
|
│ │ ├── ISatelliteDownloader.cs
|
|
│ │ └── ITileService.cs
|
|
│ └── Utils/
|
|
│ └── GeoUtils.cs
|
|
├── SatelliteProvider.DataAccess/
|
|
│ ├── SatelliteProvider.DataAccess.csproj
|
|
│ ├── DatabaseMigrator.cs
|
|
│ ├── Migrations/
|
|
│ │ ├── 001_CreateTilesTable.sql
|
|
│ │ ├── 002_CreateRegionsTable.sql
|
|
│ │ ├── 003_CreateIndexes.sql
|
|
│ │ ├── 004_AddVersionColumn.sql
|
|
│ │ ├── 005_CreateRoutesTables.sql
|
|
│ │ ├── 006_AddStitchTilesToRegions.sql
|
|
│ │ ├── 007_AddRouteMapFields.sql
|
|
│ │ ├── 008_AddGeofenceFlagToRouteRegions.sql
|
|
│ │ ├── 009_AddGeofencePolygonIndex.sql
|
|
│ │ ├── 010_AddTilesZipToRoutes.sql
|
|
│ │ └── 011_AddTileCoordinates.sql
|
|
│ ├── Models/
|
|
│ │ ├── RegionEntity.cs
|
|
│ │ ├── RouteEntity.cs
|
|
│ │ ├── RoutePointEntity.cs
|
|
│ │ └── TileEntity.cs
|
|
│ └── Repositories/
|
|
│ ├── IRegionRepository.cs
|
|
│ ├── IRouteRepository.cs
|
|
│ ├── ITileRepository.cs
|
|
│ ├── RegionRepository.cs
|
|
│ ├── RouteRepository.cs
|
|
│ └── TileRepository.cs
|
|
├── SatelliteProvider.Services/
|
|
│ ├── SatelliteProvider.Services.csproj
|
|
│ ├── GoogleMapsDownloaderV2.cs
|
|
│ ├── RegionProcessingService.cs
|
|
│ ├── RegionRequestQueue.cs
|
|
│ ├── RegionService.cs
|
|
│ ├── RouteProcessingService.cs
|
|
│ ├── RouteService.cs
|
|
│ └── TileService.cs
|
|
├── SatelliteProvider.Tests/
|
|
│ ├── SatelliteProvider.Tests.csproj
|
|
│ ├── GoogleMapsDownloaderTests.cs
|
|
│ └── appsettings.json
|
|
└── SatelliteProvider.IntegrationTests/
|
|
├── SatelliteProvider.IntegrationTests.csproj
|
|
├── Dockerfile
|
|
├── Program.cs
|
|
├── Models.cs
|
|
├── BasicRouteTests.cs
|
|
├── ComplexRouteTests.cs
|
|
├── ExtendedRouteTests.cs
|
|
├── RegionTests.cs
|
|
├── TileTests.cs
|
|
└── RouteTestHelpers.cs
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
| Category | Technology | Version |
|
|
|----------|-----------|---------|
|
|
| Language | C# | 12 (.NET 8.0) |
|
|
| Framework | ASP.NET Core (Minimal API) | 8.0 |
|
|
| Database | PostgreSQL | 16 (Docker image) |
|
|
| ORM/Data Access | Dapper | 2.1.35 |
|
|
| DB Migrations | DbUp (PostgreSQL) | 6.0.3 |
|
|
| Logging | Serilog (Console + File) | 8.0.3 |
|
|
| Image Processing | SixLabors.ImageSharp | 3.1.11 |
|
|
| JSON Serialization | Newtonsoft.Json + System.Text.Json | 13.0.4 |
|
|
| API Docs | Swagger / Swashbuckle | 6.6.2 |
|
|
| HTTP Client | IHttpClientFactory | built-in |
|
|
| Containerization | Docker (multi-stage) | - |
|
|
| Orchestration | Docker Compose | - |
|
|
| CI/CD | Woodpecker CI | - |
|
|
| Unit Testing | xUnit + Moq + FluentAssertions | 2.5.3 / 4.20.72 / 8.8.0 |
|
|
| Integration Testing | Console app (custom harness) | - |
|
|
| SDK | .NET 8.0 (latestMinor rollForward) | 8.0.0+ |
|
|
|
|
## Dependency Graph
|
|
|
|
### Project References
|
|
|
|
```
|
|
SatelliteProvider.Common (leaf — no project references)
|
|
SatelliteProvider.DataAccess (leaf — no project references; NuGet: Dapper, Npgsql, DbUp)
|
|
SatelliteProvider.Services → Common, DataAccess
|
|
SatelliteProvider.Api → Common, DataAccess, Services
|
|
SatelliteProvider.Tests → Services, Common
|
|
SatelliteProvider.IntegrationTests (standalone console app, no project references)
|
|
```
|
|
|
|
### Mermaid Dependency Diagram
|
|
|
|
```mermaid
|
|
graph TD
|
|
Api[SatelliteProvider.Api] --> Services[SatelliteProvider.Services]
|
|
Api --> DataAccess[SatelliteProvider.DataAccess]
|
|
Api --> Common[SatelliteProvider.Common]
|
|
Services --> DataAccess
|
|
Services --> Common
|
|
Tests[SatelliteProvider.Tests] --> Services
|
|
Tests --> Common
|
|
IntTests[SatelliteProvider.IntegrationTests] -.->|HTTP calls| Api
|
|
```
|
|
|
|
## Topological Processing Order
|
|
|
|
Leaf modules first, then dependent modules:
|
|
|
|
1. **SatelliteProvider.Common** — DTOs, interfaces, configs, geo utilities (no internal dependencies)
|
|
2. **SatelliteProvider.DataAccess** — entities, repositories, migrations (no project dependencies)
|
|
3. **SatelliteProvider.Services** — business logic (depends on Common + DataAccess)
|
|
4. **SatelliteProvider.Api** — web layer, DI, endpoints (depends on all above)
|
|
5. **SatelliteProvider.Tests** — unit tests (depends on Services + Common)
|
|
6. **SatelliteProvider.IntegrationTests** — integration tests via HTTP (standalone)
|
|
|
|
## Entry Points
|
|
|
|
- **Application entry**: `SatelliteProvider.Api/Program.cs` — minimal API startup, DI registration, DB migration, endpoint mapping
|
|
- **Background services**: `RegionProcessingService` (queue consumer), `RouteProcessingService` (polling loop)
|
|
- **Integration test entry**: `SatelliteProvider.IntegrationTests/Program.cs`
|
|
|
|
## Leaf Modules
|
|
|
|
- `SatelliteProvider.Common/Configs/*` — configuration POCOs
|
|
- `SatelliteProvider.Common/DTO/*` — data transfer objects
|
|
- `SatelliteProvider.Common/Interfaces/*` — service contracts
|
|
- `SatelliteProvider.Common/Utils/GeoUtils.cs` — static geo math utilities
|
|
- `SatelliteProvider.DataAccess/Models/*` — database entity classes
|
|
- `SatelliteProvider.DataAccess/Migrations/*` — SQL migration scripts
|
|
|
|
## Cycles
|
|
|
|
No dependency cycles detected. The dependency graph is a clean DAG.
|
|
|
|
## External Integrations
|
|
|
|
| Integration | Module | Protocol |
|
|
|-------------|--------|----------|
|
|
| Google Maps Tile API | GoogleMapsDownloaderV2 | HTTPS (tile.googleapis.com, mt*.google.com) |
|
|
| PostgreSQL | All repositories | TCP (Npgsql, port 5432) |
|
|
| File system (tiles) | StorageConfig, TileService, GoogleMapsDownloaderV2 | Local FS (./tiles/) |
|
|
| File system (output) | RegionService, RouteProcessingService | Local FS (./ready/) |
|
|
| File system (logs) | Serilog | Local FS (./logs/) |
|
|
|
|
## Existing Documentation
|
|
|
|
- `README.md` — comprehensive API docs, architecture overview, configuration guide
|
|
- `AGENTS.md` — agent-oriented documentation with architecture details and conventions
|
|
- `goal.md` — original requirements and TODO items
|
|
- Swagger/OpenAPI — auto-generated at runtime (`/swagger`)
|
|
|
|
## Test Structure
|
|
|
|
- **Unit tests**: `SatelliteProvider.Tests/` — xUnit, currently contains only a dummy test (`DummyTests.Dummy_ShouldWork`)
|
|
- **Integration tests**: `SatelliteProvider.IntegrationTests/` — console app that runs against a live API+DB instance in Docker. Tests cover tile downloads, region requests, route creation with intermediate points, geofencing, extended routes with map requests.
|
|
|
|
## CI/CD
|
|
|
|
- **Woodpecker CI** pipelines in `.woodpecker/`:
|
|
- `01-test.yml`: runs `dotnet restore` + `dotnet test` on push/PR to dev/stage/main (ARM64)
|
|
- `02-build-push.yml`: builds Docker image and pushes to private registry (depends on 01-test, ARM64 matrix with AMD64 slot commented out)
|