Initial GeoIntel V1 foundation

2026-06-16 23:36:32 +02:00
commit 6ea3586a3e
605 changed files with 45284 additions and 0 deletions
@@ -0,0 +1,116 @@
+# DATA ACQUISITION PLAYBOOK
+
+This playbook tells Codex how to think about data acquisition without spending the first build researching or overengineering live integrations.
+
+## Principle
+
+Sprint 1 uses local demo fixtures first. Live external data integrations are later adapters.
+
+The data hierarchy is:
+
+1. Golden fixtures for tests and UI development.
+2. Local user-uploaded files.
+3. Cached reference extracts.
+4. Live external data services.
+
+## Sprint 1 data sources
+
+### Golden GeoJSON fixtures
+
+Use existing files in `demo/geel/` as the first source of truth:
+
+- `area_geel_center.geojson`
+- `reference_buildings.geojson`
+- `demo_detections.geojson`
+- `expected_qaqc_metrics.json`
+
+These are not meant to be geographically complete. They are contract fixtures.
+
+### User upload/register
+
+Support GeoJSON first. Validate:
+
+- file extension;
+- JSON parse;
+- FeatureCollection shape;
+- geometry existence;
+- CRS handling fallback;
+- bounds calculation.
+
+## GRB strategy
+
+GRB is the professional reference layer for Vlaanderen. It is the preferred future reference for buildings and related vector features.
+
+### Sprint 1
+
+- Do not implement live GRB WFS yet.
+- Use GRB-like local fixture data.
+- Design a `ReferenceDataAdapter` interface so GRB can be added without rewriting QA/QC.
+
+### Sprint 2+
+
+- Add GRB adapter.
+- Prefer bbox/area-scoped retrieval.
+- Cache retrieved features in PostGIS.
+- Track source, retrieval timestamp and layer name.
+
+### Fallback
+
+If GRB is unavailable:
+
+- use cached extract;
+- show external-source-unavailable status;
+- do not fake live data.
+
+## OSM strategy
+
+OSM can be useful as a broad fallback/reference but must not replace GRB for professional building QA where GRB is available.
+
+### Sprint 1
+
+- No live OSM required.
+- Keep adapter boundary ready.
+
+### Later
+
+- Use Overpass or local extracts for bounded areas.
+- Cache in PostGIS.
+
+## Sentinel strategy
+
+Sentinel belongs to the Remote Sensing Lab, not Sprint 1.
+
+### Sprint 1
+
+- No Sentinel automation.
+- Do not add Copernicus dependencies.
+
+### Later
+
+- Prefer STAC-based lookup where possible.
+- Support NDVI/NDWI/NDBI through raster pipeline.
+- Cache downloaded scenes/derived rasters.
+
+## DHMV / height data strategy
+
+DHMV/DEM/DSM belongs after raster/vector foundations are stable.
+
+### Sprint 1
+
+- No height integration.
+
+### Later
+
+- Add DEM/DSM products as raster datasets.
+- Reuse raster metadata, clipping and tiling pipelines.
+
+## Data acquisition acceptance criteria
+
+A new data source is accepted only when it has:
+
+- adapter boundary;
+- source metadata;
+- cache strategy;
+- error handling;
+- tests or fixture equivalent;
+- documentation update.