# Module Build Contracts

Every module must follow this contract before it is considered build-complete.

## Common Contract
Each module must define:
- Purpose.
- Inputs.
- Outputs.
- API calls.
- Database entities touched.
- Background jobs used.
- Empty, loading, error and success UI states.
- Tests.
- Export behavior if applicable.

## Project Workspace
Purpose: manage a geospatial investigation.
Inputs: name, description, optional region preset.
Outputs: project record, workspace route.
API: `POST /api/projects`, `GET /api/projects`, `GET /api/projects/{id}`.
DB: projects.
Tests: create/list/detail.

## Area Manager
Purpose: create reusable analysis geometries.
Inputs: GeoJSON polygon or drawn polygon.
Outputs: area geometry, area size, bounds.
API: `POST /api/projects/{project_id}/areas`, `GET /api/projects/{project_id}/areas`.
DB: areas.
Validation: polygon must be valid, non-empty and inside supported broad region unless override is enabled.

## Dataset Manager
Purpose: ingest source data.
Inputs: uploaded files or source connector request.
Outputs: dataset record with extracted metadata.
API: `POST /api/projects/{project_id}/datasets`, `GET /api/projects/{project_id}/datasets`, `GET /api/datasets/{id}`.
DB: datasets, dataset_versions.
Storage: originals, processed, cache.

## Raster Lab
Purpose: inspect and prepare raster data for analysis and AI.
Inputs: raster dataset, area polygon, band config.
Outputs: metadata, preview, clipped raster, tiles.
API: `/api/raster/*`.
DB: datasets, processing_jobs, raster_outputs.

## Vector Lab
Purpose: inspect and process vector data.
Inputs: vector dataset, area polygon, operation parameters.
Outputs: clipped/intersected/buffered derived layers.
API: `/api/vector/*`.
DB: layers, derived_layers.

## Detection Lab
Purpose: run object detection and georeference outputs.
Inputs: raster dataset, model id, threshold, tile size.
Outputs: detections as PostGIS geometries and GeoJSON export.
API: `POST /api/analysis/detection-runs`.
DB: analysis_runs, detections, metrics.

## Segmentation Lab
Purpose: run segmentation and polygonize masks.
Inputs: raster dataset, model id, classes, threshold.
Outputs: segmentation polygons, masks and area metrics.
API: `POST /api/analysis/segmentation-runs`.
DB: analysis_runs, segmentations, metrics.

## QA/QC Lab
Purpose: compare AI output against reference geodata such as GRB.
Inputs: analysis run, reference dataset, class mapping, IoU threshold.
Outputs: precision, recall, F1, matched/unmatched features.
API: `POST /api/qaqc/runs`.
DB: quality_checks, quality_findings, metrics.

## Exports
Purpose: provide reusable outputs for GIS tools and portfolio demo.
Inputs: project, analysis, dataset or layer id.
Outputs: GeoJSON, CSV, report files.
API: `POST /api/exports`.
DB: exports.