geointel/docs/governance/ARCHITECTURE_INVARIANTS.md

Architecture Invariants

These invariants must remain true throughout implementation.

Core invariants

1. GeoIntel is backend/API-driven. Frontend does not own business logic.
2. PostGIS is the system of record for geometries and analysis outputs.
3. Filesystem/object storage stores binary artifacts, not authoritative feature state.
4. Heavy processing runs as jobs and reports state transitions.
5. Every analysis result belongs to an analysis_run.
6. Every detection/segmentation stores model metadata when produced by a model.
7. Every dataset stores source metadata, validation state and CRS information.
8. API responses use a consistent envelope.
9. Frontend state follows backend truth; it may cache but not invent completion states.
10. Exports are generated from persisted outputs, not transient frontend state.

Geospatial invariants

1. API GeoJSON uses EPSG:4326 unless endpoint explicitly states otherwise.
2. Belgian metric calculations use EPSG:31370 where possible.
3. Area values are stored with units.
4. Length values are stored with units.
5. Invalid geometries are fixed, rejected or marked with a validation error; never silently accepted.
6. MultiPolygon/MultiLineString handling must be explicit.
7. Geometry simplification may not mutate authoritative geometry unless a derived output is created.

AI invariants

1. AI inference is an analysis run.
2. Model outputs are candidates with confidence, not ground truth.
3. Thresholds are parameters and must be stored.
4. Tiling parameters are parameters and must be stored.
5. Model version is required for reproducibility.
6. QA/QC is separate from inference.

UI invariants

1. Every page has empty/loading/error/success states.
2. Every destructive action requires confirmation.
3. Every unavailable feature must show an honest pending state.
4. The map is a workbench surface, not a decorative background.
5. Metrics must always indicate source and timestamp.