# 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