214 lines
4.7 KiB
Markdown
214 lines
4.7 KiB
Markdown
# Backend Service Architecture
|
|
|
|
## Goal
|
|
Define service boundaries so Codex does not mix API controllers, database models, geospatial processing and AI inference into unmaintainable code.
|
|
|
|
## Service map
|
|
|
|
### ProjectService
|
|
Responsibilities:
|
|
- create/list/read/update projects
|
|
- project summary aggregation
|
|
- project-level validation
|
|
|
|
Dependencies:
|
|
- ProjectRepository
|
|
- AreaRepository
|
|
- DatasetRepository
|
|
|
|
### AreaService
|
|
Responsibilities:
|
|
- create/read/update/delete project areas
|
|
- validate geometry
|
|
- calculate area and perimeter in metric CRS
|
|
- convert API geometry to persisted PostGIS geometry
|
|
|
|
Dependencies:
|
|
- GeometryService
|
|
|
|
### DatasetService
|
|
Responsibilities:
|
|
- handle upload metadata
|
|
- create dataset records
|
|
- dispatch raster/vector import based on detected type
|
|
- manage dataset status
|
|
- store file paths and checksums
|
|
|
|
Dependencies:
|
|
- StorageService
|
|
- RasterService
|
|
- VectorService
|
|
|
|
### StorageService
|
|
Responsibilities:
|
|
- determine storage paths
|
|
- save uploaded files
|
|
- generate checksums
|
|
- create derived artifact paths
|
|
- prevent path traversal
|
|
|
|
Storage roots:
|
|
- storage/uploads
|
|
- storage/tiles
|
|
- storage/masks
|
|
- storage/reports
|
|
- exports
|
|
|
|
### RasterService
|
|
Responsibilities:
|
|
- open raster safely
|
|
- extract metadata
|
|
- clip raster by geometry
|
|
- generate tiles for inference
|
|
- calculate raster statistics/histograms
|
|
- calculate remote-sensing indices later
|
|
|
|
Libraries:
|
|
- rasterio
|
|
- numpy
|
|
- GDAL-compatible tooling if needed
|
|
|
|
### VectorService
|
|
Responsibilities:
|
|
- import GeoJSON/shapefile/GPKG where supported
|
|
- validate geometry
|
|
- fix simple invalid geometry where safe
|
|
- reproject
|
|
- clip
|
|
- buffer
|
|
- intersect
|
|
- calculate metrics
|
|
|
|
Libraries:
|
|
- geopandas
|
|
- shapely
|
|
- pyproj
|
|
|
|
### ReferenceLayerService
|
|
Responsibilities:
|
|
- fetch/cache professional reference layers
|
|
- support provider abstraction
|
|
- normalize provider output
|
|
- store cached layers in PostGIS
|
|
|
|
Providers:
|
|
- LocalFixtureReferenceProvider
|
|
- GrbWfsReferenceProvider later/configured
|
|
- OsmOverpassProvider fallback/context
|
|
|
|
### DetectionService
|
|
Responsibilities:
|
|
- create detection analysis run
|
|
- prepare raster tiles
|
|
- call detection provider
|
|
- georeference detections
|
|
- merge or suppress duplicate tile-edge detections
|
|
- persist detections
|
|
- produce layer metadata
|
|
|
|
Providers:
|
|
- DevelopmentDetectionProvider for deterministic fixtures
|
|
- YoloDetectionProvider
|
|
|
|
### SegmentationService
|
|
Responsibilities:
|
|
- create segmentation analysis run
|
|
- prepare input raster/tile/mask workflow
|
|
- call segmentation provider
|
|
- persist mask artifacts
|
|
- polygonize masks where possible
|
|
- persist segmentation geometries
|
|
|
|
Providers:
|
|
- DevelopmentSegmentationProvider
|
|
- SamSegmentationProvider later
|
|
- YoloSegmentationProvider later
|
|
|
|
### QaqcService
|
|
Responsibilities:
|
|
- compare prediction geometries with reference geometries
|
|
- calculate IoU and matching
|
|
- calculate precision/recall/F1
|
|
- persist quality check summary and findings
|
|
- generate layers for matched/false-positive/false-negative outputs
|
|
|
|
Dependencies:
|
|
- GeometryService
|
|
- AnalysisRunRepository
|
|
|
|
### ChangeDetectionService
|
|
Responsibilities:
|
|
- compare baseline and comparison layers
|
|
- identify added/removed/changed geometries
|
|
- persist change features and metrics
|
|
|
|
### ExportService
|
|
Responsibilities:
|
|
- export vectors as GeoJSON
|
|
- export run package with metadata
|
|
- export simple Markdown/HTML report
|
|
- record export history
|
|
|
|
### JobService
|
|
Responsibilities:
|
|
- enqueue long-running operations
|
|
- track status/progress/logs
|
|
- support retry/failure status
|
|
|
|
V1 may implement synchronous execution first for small fixtures, but service boundaries must allow async jobs later.
|
|
|
|
### GeometryService
|
|
Responsibilities:
|
|
- CRS conversion helpers
|
|
- area/length calculations in metric CRS
|
|
- geometry validation
|
|
- IoU calculation
|
|
- spatial matching helpers
|
|
|
|
## API layer rule
|
|
API routes may:
|
|
- validate request schema
|
|
- call service methods
|
|
- return response schema
|
|
|
|
API routes may not:
|
|
- perform direct geospatial processing
|
|
- access files directly
|
|
- contain model inference logic
|
|
- contain PostGIS SQL beyond simple repository usage
|
|
|
|
## Repository layer rule
|
|
Repositories handle database access only. They should not know about Rasterio, YOLO, MapLibre or UI concerns.
|
|
|
|
## Error handling
|
|
All services must raise typed application errors:
|
|
- NotFoundError
|
|
- ValidationError
|
|
- ProcessingError
|
|
- UnsupportedDatasetError
|
|
- ExternalProviderError
|
|
- GeospatialError
|
|
|
|
API layer maps these to proper HTTP responses.
|
|
|
|
## Logging
|
|
Every analysis run should record:
|
|
- start time
|
|
- end time
|
|
- parameters
|
|
- status
|
|
- failure reason if failed
|
|
- output artifact paths
|
|
|
|
## V1 service acceptance
|
|
V1 backend foundation is acceptable when the following services exist even if some methods are minimal:
|
|
- ProjectService
|
|
- AreaService
|
|
- DatasetService
|
|
- StorageService
|
|
- RasterService
|
|
- VectorService
|
|
- DetectionService
|
|
- QaqcService
|
|
- ExportService
|