# 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.