Initial GeoIntel V1 foundation

docs/13-implementation-traps/API_RESPONSE_RULES.md

@@ -0,0 +1,79 @@
+# API Response Rules
+
+All API responses must be stable and implementation-friendly.
+
+## Success Envelope
+
+For single resources:
+
+```json
+{
+  "data": {},
+  "meta": {}
+}
+```
+
+For lists:
+
+```json
+{
+  "data": [],
+  "meta": {
+    "count": 0,
+    "limit": 50,
+    "offset": 0
+  }
+}
+```
+
+## Error Envelope
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human readable message",
+    "details": {},
+    "trace_id": "optional"
+  }
+}
+```
+
+## Required Resource Fields
+
+Most persisted resources should include:
+
+- `id`
+- `created_at`
+- `updated_at`
+
+Geospatial resources should also include:
+
+- `crs`
+- `bounds`
+- `geometry_type` where applicable
+
+Analysis resources should include:
+
+- `status`
+- `parameters`
+- `outputs`
+- `metrics`
+- `error_message` when failed
+
+## Pagination
+
+Use `limit` and `offset` for V1. Cursor pagination can be added later if needed.
+
+## Sorting
+
+Default sort: newest first for projects, datasets, analyses and exports.
+
+## Contract Drift Rule
+
+If implementation changes any response shape, update:
+
+- `contracts/api/`
+- API docs
+- frontend API client types
+- tests

docs/13-implementation-traps/FRONTEND_STATE_RULES.md

@@ -0,0 +1,70 @@
+# Frontend State Rules
+
+GeoIntel frontend must be predictable, API-driven and resistant to partial build regressions.
+
+## State Layers
+
+Use three state categories:
+
+1. Server state: projects, datasets, areas, analysis runs, metrics, exports.
+2. UI state: selected tab, open panel, layer opacity, map camera.
+3. Draft state: unsaved polygon, upload form, threshold slider before run.
+
+Server state must be loaded through API client functions. Do not duplicate server truth in Zustand except as cached references managed by query tooling.
+
+## Required Page States
+
+Every data-driven page must render:
+
+- initial loading
+- empty state
+- error state
+- ready state
+- processing state when jobs exist
+
+## Map State
+
+Map layer state must include:
+
+- id
+- name
+- source
+- visibility
+- opacity
+- style
+- legend label
+- feature count if known
+
+## Analysis Run State
+
+Analysis run UI must display:
+
+- status
+- started_at
+- completed_at when available
+- parameters
+- model mode if AI-related
+- output layers
+- metrics
+- errors if failed
+
+## Form Validation
+
+Client validation improves UX but must not replace backend validation.
+
+## Navigation
+
+The navigation should preserve the mental model:
+
+- Projects
+- Workspace
+- Map
+- Datasets
+- Raster
+- Vector
+- Detection
+- Segmentation
+- QA/QC
+- Exports
+
+Do not hide core modules behind unrelated dashboard labels.

docs/13-implementation-traps/GEOSPATIAL_CALCULATION_RULES.md

@@ -0,0 +1,87 @@
+# Geospatial Calculation Rules
+
+These rules define how GeoIntel must handle geospatial calculations.
+
+## Coordinate Reference Systems
+
+Default display CRS: EPSG:4326.
+
+Default metric calculation CRS for Flanders/Kempen: EPSG:31370.
+
+Every dataset must store:
+
+- source CRS
+- normalized/display CRS if converted
+- metric calculation CRS used for area/distance outputs
+
+## Geometry Validation
+
+Before inserting vector features:
+
+1. check geometry exists
+2. check geometry type
+3. check validity
+4. check empty geometry
+5. compute bounds
+6. compute source feature count
+
+Invalid geometries should be recorded in dataset metadata. Auto-fix may be attempted using buffer(0) or make_valid only if the metadata records this correction.
+
+## Area Calculation
+
+Area values must include units.
+
+Preferred units:
+
+- `m2` for feature-level area
+- `ha` for summary land cover areas
+- `km2` for large area summaries
+
+Never calculate area from EPSG:4326 degrees.
+
+## Distance Calculation
+
+Distance values must include units.
+
+Preferred units:
+
+- `m` for local distances
+- `km` for totals and densities
+
+## Density Calculation
+
+Densities must define denominator:
+
+- buildings per km2
+- road km per km2
+- vegetation ha per km2
+
+## IoU Calculation
+
+For polygons A and B:
+
+`IoU = area(intersection(A, B)) / area(union(A, B))`
+
+Both geometries must be projected to metric CRS before area calculation.
+
+## Matching Rule
+
+Default object matching threshold for building QA/QC:
+
+`IoU >= 0.5`
+
+Alternative thresholds may be exposed in UI but must default to 0.5 for first V1 implementation.
+
+## Precision, Recall and F1
+
+- TP: predicted feature matched to one reference feature above threshold
+- FP: predicted feature without reference match
+- FN: reference feature without predicted match
+
+`precision = TP / (TP + FP)`
+
+`recall = TP / (TP + FN)`
+
+`f1 = 2 * precision * recall / (precision + recall)`
+
+If denominator is zero, return null and include explanatory reason.