2.4 KiB
Regression Traps
This document lists common failure modes Codex must actively avoid.
Geospatial Traps
CRS Loss
Never store or return geometries without CRS context. GeoJSON is usually WGS84 by convention, but source CRS must still be preserved in dataset metadata.
Bounding Box Confusion
Never mix [minx, miny, maxx, maxy] with [west, south, east, north] without explicitly naming fields.
Area Units
Never compute area in degrees. Reproject to an appropriate projected CRS before area or distance calculations. For Flanders/Kempen, prefer Belgian Lambert 72 / EPSG:31370 for metric calculations unless a stronger reason is documented.
Raster/Vector Alignment
Never compare raster-derived outputs with vector reference layers without documenting resolution, CRS and alignment assumptions.
Invalid Geometry
Always validate polygons. Attempt safe fixes only when documented; otherwise return a validation error.
AI Traps
Confidence Is Not Accuracy
Do not present model confidence as accuracy. Accuracy requires comparison against reference or labels.
Fixture Detection Is Not Real AI
When using fixture/stub output, label it clearly as fixture/demo mode.
Silent Model Fallback
Never silently fall back from real model inference to fixture mode. The response must indicate the mode used.
Mask Polygonization Noise
Segmentation polygonization must include simplification/cleanup parameters and preserve original mask path.
Backend Traps
Long Work in Request Thread
Do not run heavy raster/AI operations synchronously inside request handlers. Use a job boundary.
Inconsistent Status Values
Use the frozen status enum only: queued, running, completed, failed, cancelled.
File Path Leakage
API responses may expose logical storage keys or download URLs, not arbitrary host paths.
Frontend Traps
UI-Only State
Do not create project, area, dataset or analysis state only in frontend memory. Persist via API.
Empty Success Screens
Every page must distinguish loading, empty, error, ready and completed states.
Map Layer Ambiguity
Every map layer must show source, timestamp, opacity, visibility and legend where applicable.
Documentation Traps
TODO Instead of Decision
Do not use TODO comments for architecture gaps. Either implement, document a limitation, or ask for a decision.
Contract Drift
If code changes API responses, update contract docs and examples in the same pass.