geointel/docs/specs/CANONICAL_DOMAIN_MODELS.md

Canonical Domain Models

This document defines shared concepts. All backend services, frontend types and tests must use these definitions.

Project

A Project is an investigation container.

Required behavior:

• contains Areas, Datasets, AnalysisRuns and Exports;
• has a human-readable name and optional description;
• may contain demo or real data, but the data mode must be visible;
• does not directly store geospatial features except through child entities.

Area

An Area is a geospatial boundary used to clip, filter and analyze data.

Required fields:

• id
• project_id
• name
• geometry
• geometry_crs
• area_m2
• bounds_4326
• created_at

Rules:

• API representation is GeoJSON EPSG:4326.
• Internal metric operations should use EPSG:31370 for Kempen/Belgium.
• Area can be a free polygon, municipality-derived polygon or demo fixture.

Dataset

A Dataset is a registered data source or uploaded file.

Dataset types:

• raster
• vector
• reference_vector
• model_output
• mask
• export

Required behavior:

• original artifact is preserved;
• metadata extraction produces a metadata record;
• validation state is explicit;
• derived datasets reference parents.

Layer

A Layer is a map-renderable view of a dataset or analysis output.

Rules:

• layers have styling metadata;
• layers do not own authoritative geometry;
• layer visibility is frontend state, not processing state.

AnalysisRun

An AnalysisRun is one execution of a processing pipeline.

Examples:

• raster metadata extraction;
• vector clipping;
• object detection;
• segmentation;
• QA/QC;
• export generation.

Required fields:

• id
• project_id
• area_id optional
• analysis_type
• status
• parameters_json
• started_at
• finished_at
• error_code optional
• error_message optional

Detection

A Detection is a candidate object produced or imported as an analysis output.

Required fields:

• class name;
• confidence;
• geometry;
• bbox;
• source analysis run;
• model metadata if AI-produced;
• source tile if tiled inference was used.

Segmentation

A Segmentation is a polygon or raster mask representing class coverage.

Required fields:

• class name;
• geometry or mask path;
• area_m2;
• confidence/score if available;
• source analysis run;
• model metadata if AI-produced.

ReferenceFeature

A ReferenceFeature is an authoritative or semi-authoritative feature used for validation.

V1 examples:

• GRB-like building polygons;
• demo reference buildings;
• OSM fallback buildings.

QualityCheck

A QualityCheck compares candidate outputs to reference data or validates dataset integrity.

Required outputs:

• metric values;
• method;
• thresholds;
• matched/unmatched features where applicable;
• pass/fail or warning status.

Export

An Export is a generated artifact derived from persisted state.

Allowed V1 exports:

• GeoJSON;
• CSV metrics;
• simple HTML/Markdown report if trivial;
• not mandatory: complex PDF.