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,43 @@
+# Codex Handoff Briefing
+
+You are inheriting GeoIntel Kempen, a GeoAI Workbench for the Belgian Kempen.
+
+## Read first
+
+1. `README.md`
+2. `AGENTS.md`
+3. `docs/V1_SCOPE_FREEZE.md`
+4. `docs/SERVICE_ARCHITECTURE.md`
+5. `docs/REPOSITORY_CONVENTIONS.md`
+6. `docs/15-tomorrow-execution/M8_TOMORROW_EXECUTION_PACK.md`
+7. `docs/15-tomorrow-execution/DAY_1_EXECUTION_TIMELINE.md`
+8. the current pass prompt under `prompts/codex/day-1/`
+
+## Build philosophy
+
+Build thin but real vertical slices. Do not hide missing functionality behind convincing UI. A small working API with tests is better than a beautiful mock.
+
+## The first usable vertical slice
+
+The first vertical slice is:
+
+```text
+Project -> Area -> Dataset registration -> Metadata -> Map/Workbench display -> Export-ready internal structure
+```
+
+Object detection, segmentation and QA/QC are important, but they must sit on a stable foundation.
+
+## Common failure modes to avoid
+
+- Creating frontend-only mock data that bypasses API state.
+- Mixing geometry parsing into random route handlers.
+- Adding AI dependencies before the data model is stable.
+- Hardcoding local file paths.
+- Ignoring CRS metadata.
+- Creating database models that cannot handle future PostGIS geometries.
+- Implementing upload without storage policy.
+- Writing TODOs instead of completing the requested pass.
+
+## Improvement freedom
+
+You may add helper modules, stricter validation, better tests, and cleaner component structure. You may not change the product scope or stack.
@@ -0,0 +1,124 @@
+# Day 1 Execution Timeline
+
+This is a practical day plan for Codex. Times are indicative, not strict.
+
+## Block 0 — Repository audit
+
+Goal: understand the repo, identify existing docs, confirm no missing foundation files.
+
+Deliverables:
+
+- updated `docs/CODEX_EXECUTION_LOG.md`;
+- short implementation plan;
+- no product scope changes.
+
+Do not implement features in this block.
+
+## Block 1 — Backend foundation
+
+Goal: create the minimal FastAPI application architecture.
+
+Deliverables:
+
+- app factory or main app;
+- health endpoint;
+- config module;
+- logging setup;
+- consistent response/error envelope;
+- backend test harness.
+
+Acceptance:
+
+- backend imports cleanly;
+- health test passes;
+- no database dependency required for health endpoint.
+
+## Block 2 — Database and domain
+
+Goal: add SQLAlchemy/Alembic/PostGIS-ready domain foundation.
+
+Deliverables:
+
+- database config;
+- migration folder;
+- core models for projects, areas, datasets, analysis_runs, exports;
+- geometry strategy documented in code comments where needed.
+
+Acceptance:
+
+- migrations run on local Postgres/PostGIS;
+- tests can run with a safe test DB or mocked DB session layer;
+- no raw geometry hacks in API layer.
+
+## Block 3 — Project, Area and Dataset APIs
+
+Goal: implement first real domain APIs.
+
+Deliverables:
+
+- create/list/read projects;
+- create/list/read areas;
+- dataset registration/upload scaffold;
+- validation schemas;
+- contract tests.
+
+Acceptance:
+
+- documented API contract examples match actual responses;
+- invalid GeoJSON produces structured validation error;
+- areas store geometry metadata.
+
+## Block 4 — Frontend shell
+
+Goal: create a navigable frontend shell matching the workbench model.
+
+Deliverables:
+
+- Vite/React/TypeScript app;
+- route layout;
+- left navigation;
+- workspace pages;
+- API client with typed methods;
+- empty/loading/error states.
+
+Acceptance:
+
+- frontend runs;
+- routes do not crash;
+- API base URL is environment-driven;
+- no random fake product flow.
+
+## Block 5 — Raster/vector metadata
+
+Goal: add the first geospatial processing services.
+
+Deliverables:
+
+- vector metadata parser for GeoJSON;
+- raster metadata service scaffold using Rasterio when available;
+- dataset metadata endpoint;
+- fixture-driven tests.
+
+Acceptance:
+
+- fixtures return deterministic metadata;
+- unsupported file type returns controlled error;
+- processing outputs are stored according to storage spec.
+
+## Block 6 — Vertical slice stabilization
+
+Goal: make the foundation coherent.
+
+Deliverables:
+
+- smoke script;
+- updated docs;
+- TODO checked/updated;
+- changelog entry;
+- known limitations list.
+
+Acceptance:
+
+- one command or documented sequence verifies backend + frontend basics;
+- no broken imports;
+- no undocumented architectural shortcuts.
@@ -0,0 +1,84 @@
+# M8 Tomorrow Execution Pack
+
+This package exists so Codex can start tomorrow with minimal manual steering.
+
+## Operating mode
+
+Codex must work in controlled autonomous passes. Each pass must:
+
+1. read the relevant docs before editing;
+2. implement one coherent layer only;
+3. run the documented validation commands;
+4. write a concise completion report;
+5. update TODO, CHANGELOG and CODEX_EXECUTION_LOG;
+6. stop when a blocker requires product/architecture judgement.
+
+## Non-negotiable product direction
+
+GeoIntel Kempen is a **GeoAI Workbench**, not a generic dashboard and not a CRUD demo.
+The V1 vertical slice must prove:
+
+- geospatial project/area/dataset management;
+- raster/vector metadata extraction;
+- map-based spatial workflow;
+- PostGIS-ready geometry handling;
+- controlled AI detection pipeline scaffolding;
+- QA/QC against reference geodata;
+- geospatial export.
+
+## Day-1 success condition
+
+A successful first Codex day should end with a running foundation that can be started locally and demonstrates:
+
+- backend health endpoint;
+- database connection and migrations;
+- project/area/dataset APIs;
+- frontend shell with routes;
+- map workspace placeholder wired to API state;
+- deterministic fixtures and smoke checks;
+- no uncontrolled mock-only business logic.
+
+## Recommended execution order
+
+1. `prompts/codex/day-1/00_START_HERE.md`
+2. `prompts/codex/day-1/01_REPO_AUDIT_AND_PLAN.md`
+3. `prompts/codex/day-1/02_BACKEND_FOUNDATION.md`
+4. `prompts/codex/day-1/03_DATABASE_AND_DOMAIN.md`
+5. `prompts/codex/day-1/04_PROJECT_AREA_DATASET_API.md`
+6. `prompts/codex/day-1/05_FRONTEND_SHELL.md`
+7. `prompts/codex/day-1/06_RASTER_VECTOR_METADATA.md`
+8. `prompts/codex/day-1/07_VERTICAL_SLICE_STABILIZATION.md`
+
+## What Codex may improve without asking
+
+Codex may improve naming, folder hygiene, small helper abstractions, test coverage, typing, validation, error messages, and developer ergonomics if the changes preserve the documented contracts.
+
+## What Codex may not change without explicit approval
+
+Codex may not change:
+
+- product positioning;
+- selected stack;
+- V1 scope boundaries;
+- database aggregate names;
+- API envelope conventions;
+- storage layout;
+- QA/QC metric definitions;
+- GRB as primary reference strategy;
+- incremental build discipline.
+
+## Required end-of-pass response format
+
+Every pass must end with:
+
+```text
+PASS COMPLETED: <name>
+CHANGED FILES:
+- ...
+VALIDATION RUN:
+- command: result
+OPEN ISSUES:
+- ... or none
+NEXT RECOMMENDED PASS:
+- ...
+```
@@ -0,0 +1,31 @@
+# Next Pass After Day 1
+
+If Day 1 succeeds, the next priority is not broad feature expansion. The next priority is the first true GeoAI/GIS capability.
+
+## Preferred Day 2 sequence
+
+1. GRB/reference adapter scaffold.
+2. Raster tiling interface.
+3. Detection model registry scaffold.
+4. Deterministic detection fixture adapter.
+5. Detection output as GeoJSON.
+6. QA/QC overlap metrics against reference fixture.
+7. Map overlay display.
+
+## Why this sequence
+
+It creates the first portfolio-relevant technical loop:
+
+```text
+Raster/Dataset -> Detection -> Geospatial output -> Reference comparison -> QA metrics -> Export
+```
+
+## Do not jump directly to
+
+- full SAM integration;
+- real Sentinel downloads;
+- LiDAR processing;
+- training studio;
+- complex report generation.
+
+Those need the Day 1 foundation and Day 2 detection/QA loop first.