geointel/docs/MODULE_BUILD_CONTRACTS.md

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.