Initial public release

docs/SERVICE_ARCHITECTURE.md

@@ -0,0 +1,213 @@
+# 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