geointel/docs/SERVICE_ARCHITECTURE.md

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