geointel/docs/TODO.md

# GeoIntel TODO

This file now starts with the current implementation status. Older preparation/backlog sections are preserved below as historical planning context and should not be treated as the live sprint board without checking `docs/CODEX_EXECUTION_LOG.md`.

## Release hardening status

- [x] Remove Python `datetime.utcnow()` deprecation warnings from backend service paths.
- [x] Split frontend production build into app, React vendor and MapLibre vendor chunks.
- [x] Enforce Python deprecation warnings as release-readiness failures.
- [x] Fix Docker backend package install order and remove mandatory root `.env` dependency.
- [x] Add Docker build context ignores for backend and frontend.
- [x] Run Docker/PostGIS live validation on Tower/Unraid.
- [x] Add Unraid Compose template assets with editable ports, storage path and app icon.
- [x] Add single-container Unraid runtime with embedded PostGIS, backend and frontend.
- [x] Remove embedded PostGIS password defaults from all-in-one Docker image metadata.
- [x] Report reused-volume PostgreSQL collation mismatches in live migration smoke.
- [x] Execute Tower PostgreSQL collation reindex/refresh after backup.

## Current implementation status

- [x] Backend FastAPI foundation, health endpoint and service structure.
- [x] React/TypeScript frontend foundation and MapLibre workbench.
- [x] Map layer visibility, opacity and feature property inspection.
- [x] Selected project area/AOI map overlay with visibility and opacity controls.
- [x] SQLAlchemy/PostGIS ORM models and Alembic migration chain through Sprint 9.
- [x] Dataset upload, storage metadata and vector feature persistence.
- [x] Raster metadata and raster operation service boundaries.
- [x] Vector operation service boundaries and fixture-backed tests.
- [x] Provider registry skeleton for GRB, OSM, manual and fixture providers.
- [x] Detection Lab foundation, persistence, GeoJSON output and QA integration.
- [x] Configured-YOLO optional dependency strategy and local preflight.
- [x] Segmentation Lab foundation, persistence, GeoJSON output and QA integration.
- [x] QA/QC golden benchmark fixtures and script.
- [x] Run QA/QC golden benchmark from the main readiness gate.
- [x] Verify browser-facing demo QA/QC metrics against the golden baseline.
- [x] Explicit offline demo workflow seed for project, AOI, fixture datasets and persisted QA metrics.
- [x] Project-scoped QA/QC result listing and frontend QA/QC Results panel.
- [x] Persisted export foundation for vector/detection/segmentation GeoJSON and project metadata JSON.
- [x] Lightweight HTML project report artifact export.
- [x] V1 readiness handoff summary in project metadata/report exports.
- [x] Browser-facing demo/export workflow smoke script with connected V1 state checks.
- [x] Compact V1 workbench status strip for project, AOI, datasets, map, QA/QC and exports.
- [x] Dry-run-first demo export artifact cleanup tooling.
- [x] Browser-facing default workbench state smoke for the offline demo project.
- [x] Browser-facing workbench interaction backing-state smoke and stable UI test anchors.
- [x] Backend API contract audit comparing implemented FastAPI routes with `docs/API_CONTRACTS.md`.
- [x] Live Docker/PostGIS validation on Tower/Unraid.
- [x] Real YOLO compatibility smoke with optional AI extras and local model file.
- [x] Detection and segmentation workflow hook extraction beyond Sprint 10.
- [x] Export and QA/QC workflow hook extraction beyond Sprint 10.
- [x] Dataset, raster and vector workflow hook extraction beyond Sprint 10.
- [x] Dataset detail, raster controls and vector controls component decomposition.
- [x] QA/QC results and map workspace component decomposition.
- [x] Docker Compose port/storage/database configuration via `.env` defaults for Unraid.
- [x] Single-container `geointel` Unraid compose/template runtime.
- [x] Export preview component decomposition and HTML report download-only UX hardening.
- [x] Provider, change-detection and map-workspace orchestration hook decomposition.
- [x] Project/area/dataset cross-load orchestration hook decomposition.
- [x] Demo workflow orchestration hook decomposition.
- [x] Final `App.tsx` import/encoding cleanup and size audit.
- [x] Optional final bootstrap-effect extraction.
- [x] Decide next V1 stabilization focus: golden dataset expansion or frontend visual polish backlog.
- [x] Expand golden QA/QC benchmark coverage across partial, perfect, no-overlap and MultiPolygon scenarios.
- [x] Improve workbench shell visual polish, mobile navigation density and AI result readability.
- [x] Improve Map workspace layer provenance, empty guidance and selected-feature summary readability.
- [x] Add Data/Map mobile visual polish for upload forms, action grids and map toolbar density.
- [x] Add AI Labs mobile visual polish for model cards, lab forms and result tables.
- [x] Add Export/System mobile visual polish for export actions and provider capability cards.
- [x] Add inspector mobile polish for dataset metadata, raster/vector tools and action groups.
- [x] Add export preview readability polish for large JSON/GeoJSON handoff artifacts.
- [x] Add accessibility focus polish for primary workbench keyboard navigation.
- [x] Add raster/vector operation form readability polish for dense tool panels.
- [x] Add compact loading/error/empty/result state polish across QA, exports and AI labs.
- [x] Add compact shell density polish for topbar context, mobile navigation and workspace skip flow.
- [x] Add Overview workspace panel hierarchy polish for readiness and recommended-action regions.
- [x] Add Data workspace selected-summary and panel density polish.
- [x] Add Map workspace panel hierarchy and layer-control density polish.
- [x] Add selected map feature extraction with highlight, property table, copy and GeoJSON download.
- [x] Add operational GIS map workflow with road basemap, persisted database layer selection and AOI/layer `vector_features` query run.
- [x] Add basemap policy notice and guided GIS query-to-QA/export workflow in the Map workspace.
- [x] Add reusable latest-result mode for repeated Map QA/QC runs without duplicate derived artifacts.
- [x] Add opt-in Docker/Unraid AI build/runtime path for local PyTorch/Ultralytics YOLO operation.
- [x] Surface configured-YOLO runtime preflight status through the API and Detection Lab UI.
- [x] Add read-only local model asset catalog and Detection Lab model-file selection.
- [x] Add live model asset detection workflow smoke for configured-YOLO runtime/provenance validation.
- [x] Add one-click full GIS workflow action for query, derived dataset, QA/QC and export handoff.
- [x] Add QA/QC workspace result hierarchy and filter density polish.
- [x] Add Change Detection panel hierarchy and analysis workspace density polish.
- [x] Add calm workbench layout pass to reduce duplicate navigation, heavy card styling and shell density.
- [x] Add Data and Map usability layout pass with compact catalog cards and map-first spatial review.
- [x] Add QA/QC and Exports usability layout pass with calmer evidence review and handoff artifact scanning.
- [x] Add AI Labs Detection/Segmentation hierarchy and result density polish.
- [x] Add Export/System handoff hierarchy and provider registry density polish.
- [x] Add operator-provided real raster/reference detection + QA workflow smoke.
- [x] Validate the configured building model on a real georeferenced Kempen orthophoto/GeoTIFF with persisted reference vectors and QA/QC metrics.
- [x] Fix configured-YOLO mixed-case class labels so `Building` model output matches `building` domain filters.
- [x] Persist CRS metadata in raster tile manifests so AI detections can be transformed to WGS84 GeoJSON correctly.
- [x] Add real-data detection calibration sweep tooling for confidence-threshold and QA/QC metric comparison.
- [x] Add calibration QA evidence export tooling for false-positive/false-negative inspection artifacts.
- [x] Add real-data detection quality matrix tooling for model/tile/threshold comparison.
- [x] Add reproducible Geel/Mol/Turnhout operator sample preparation and multi-sample quality matrix tooling.
- [x] Run first Geel/Mol/Turnhout persisted detection quality baseline.
- [x] Add and benchmark a stronger `yolov8s` building-segmentation runtime model candidate.
- [x] Add operator-only tile-level YOLO dataset export with overlapping windows and deterministic negative tile retention.
- [x] Train and benchmark the first tile-level local YOLO candidate on Tower through the persisted QA/QC matrix.
- [x] Calibrate confidence, IoU and model selection against additional local orthophoto/reference samples beyond Geel/Mol/Turnhout.
- [x] Add negative/background AOIs to the operator sample corpus and train an expanded local tile-level YOLO candidate.
- [x] Add a hard-negative model-quality pass with sparse/background AOIs and explicit false-positive scoring.
- [x] Train a hard-negative-balanced YOLO candidate and rerun dense QA plus background false-positive matrices.
- [x] Benchmark an external remote-sensing YOLOv8l building candidate as an explicit local model asset.
- [ ] Find or train a materially stronger aerial/Kempen building model candidate; `geointel-building-yolov8n-expanded160e50-pt` is the best current dense-AOI candidate but still too weak and too noisy for a V1 default.
- [ ] Train a higher-capacity local aerial-building detector with stronger positive recall while preserving the hard-negative false-positive gate.

## Sprint 8 status

- [x] Detection foundation ORM and migration
- [x] Detection model registry capability stubs
- [x] Detection run service boundary
- [x] Detection API foundation
- [x] Detection Lab UI foundation
- [x] Segmentation Lab foundation
- [x] Configured YOLO local preflight
- [x] Real YOLO/PyTorch model compatibility smoke

## 0. Repository Foundation

- [x] Repo mappenstructuur voorbereiden
- [x] Productdocumentatie voorbereiden
- [x] Architectuurdocumentatie voorbereiden
- [x] Codex build plan voorbereiden
- [x] Masterprompt voorbereiden
- [ ] Init git repository
- [x] Voeg echte backend scaffold toe
- [x] Voeg echte frontend scaffold toe

## 1. Backend Foundation

- [x] FastAPI app aanmaken
- [x] Config systeem aanmaken
- [x] Database connectie voorbereiden
- [x] SQLAlchemy models toevoegen
- [x] Alembic migrations toevoegen
- [x] Health endpoint toevoegen
- [x] Tests voor health endpoint toevoegen

## 2. Database / PostGIS

- [x] Docker compose met PostgreSQL/PostGIS
- [x] PostGIS extensie activeren
- [x] projects tabel
- [x] areas tabel
- [x] datasets tabel
- [x] analysis_runs tabel
- [x] detections tabel
- [x] quality_checks tabel
- [x] exports tabel
- [x] spatial indexes

## 3. Frontend Foundation

- [x] React + TypeScript scaffold
- [x] Routing
- [x] Layout met sidebar
- [x] API client
- [x] Project pages
- [x] Map Workbench basis
- [x] Map layer controls
- [x] Feature property inspector
- [x] Selected area display

## 4. Project & Area API

- [ ] POST /projects
- [ ] GET /projects
- [ ] GET /projects/{id}
- [ ] POST /projects/{id}/areas
- [ ] GET /projects/{id}/areas
- [ ] GeoJSON validatie

## 5. Dataset Manager

- [ ] Upload endpoint
- [ ] Storage paths
- [ ] Raster metadata extraction
- [ ] Vector metadata extraction
- [ ] Dataset list UI
- [ ] Dataset detail UI

## 6. Raster Core

- [ ] Rasterio metadata reader
- [ ] Raster preview generation
- [ ] Clip raster by area
- [ ] Tile raster by area
- [ ] Save tile metadata

## 7. Vector Core

- [ ] GeoPandas importer
- [ ] CRS detection
- [ ] CRS transformation
- [ ] Geometry validation
- [ ] Clip vector by area
- [ ] Store features in PostGIS

## 8. Reference Data

- [ ] OSM fetcher als fallback
- [ ] GRB integration research verwerken in code
- [ ] Reference dataset cache
- [ ] Reference layer viewer

## 9. Detection Lab

- [ ] YOLO wrapper
- [ ] Model config
- [ ] Inference job
- [ ] Pixel bbox naar geo polygon
- [ ] Detections opslaan
- [ ] Detection UI
- [ ] GeoJSON export

## 10. QA/QC Lab

- [ ] Spatial matching
- [ ] IoU berekening
- [ ] Precision/recall/F1
- [ ] False positive layer
- [ ] False negative layer
- [x] QA dashboard
- [x] QA export foundation

## 11. Segmentation Lab

- [x] Segmentation service design
- [x] Mask artifact path convention
- [ ] Polygonize masks
- [x] Segmentatiekaartlaag

## 12. Change Detection

- [ ] Compare two runs
- [x] Added/removed objects
- [x] Change stats
- [x] Change layer

## 13. Tests

- [x] Unit tests GIS helpers
- [x] API tests
- [x] DB/migration smoke tests
- [x] Raster fixture tests
- [x] Vector fixture tests
- [x] QA/QC tests

## 14. Portfolio Release

- [x] Demo dataset voorbereiden
- [x] Demo workflow documenteren
- [ ] Screenshots toevoegen
- [ ] README portfolio sectie
- [ ] Full smoke test

# Repo preparation additions

- [x] Add Data Catalog.
- [x] Add Analysis Specifications.
- [x] Add QA/QC Specification.
- [x] Add Raster Operations Specification.
- [x] Add Vector Operations Specification.
- [x] Add Detection Pipeline Specification.
- [x] Add Segmentation Pipeline Specification.
- [x] Add Change Detection Specification.
- [x] Add UI Page Specifications.
- [x] Add Storage Architecture.
- [x] Add Demo Scenarios.
- [x] Add Development Rules.
- [x] Add Codex phase prompts.

# Recommended first Codex build sequence

- [ ] Phase 1: Backend foundation using `docs/CODEX_PHASE_1_PROMPT.md`.
- [ ] Phase 2: Dataset Manager using `docs/CODEX_PHASE_2_PROMPT.md`.
- [ ] Phase 3: Detection + QA/QC skeleton using `docs/CODEX_PHASE_3_PROMPT.md`.

## M2 Engineering Package

- [x] Add ADR decision records.
- [x] Add RFC placeholders for future modules.
- [x] Add API/database/event contracts.
- [x] Add model registry and class catalogs.
- [x] Add queue architecture.
- [x] Add acceptance matrix and test catalog.
- [x] Add Codex M2 build prompts.
- [ ] Start Codex Pass 01 backend foundation.

# M4 Autonomous Build Readiness

- [x] Add M4 autonomous build readiness document.
- [x] Add M4 sprint board.
- [x] Add module build contracts.
- [x] Add acceptance test catalog.
- [x] Add API example responses.
- [x] Add job lifecycle contract.
- [x] Add frontend state and route contracts.
- [x] Add backend service IO contracts.
- [x] Add model registry seed specification.
- [x] Add demo fixture manifest.
- [x] Add Codex autonomous runbook.
- [x] Add Codex pass prompts.
- [x] Add Geel demo fixtures.

# Next M5 Preparation

- [ ] Add concrete SQL migration snippets for every core table.
- [ ] Add OpenAPI YAML draft.
- [ ] Add frontend component prop contracts.
- [ ] Add backend unit-test skeleton files.
- [ ] Add frontend test skeleton files.
- [ ] Add live data connector research notes with verified endpoints.

# M5 Operational Readiness Checklist

- [x] CI/CD specification added.
- [x] Healthcheck contracts added.
- [x] Observability plan added.
- [x] Troubleshooting runbook added.
- [x] Rollback and recovery plan added.
- [x] Security checklist added.
- [x] Geospatial validation rules added.
- [x] Build governance added.
- [x] Codex pass documents added.
- [x] Smoke scripts added.
- [ ] M6: implement actual backend foundation.
- [ ] M6: implement database migrations.
- [ ] M6: implement frontend shell.

## M8 Codex Day-1 Readiness

- [x] Add Day 1 master prompt.
- [x] Add pass-by-pass Day 1 prompts.
- [x] Add autonomy boundaries.
- [x] Add failure recovery playbook.
- [x] Add quality gate matrix.
- [x] Add operator checklist.
- [x] Add smoke script scaffold.
- [ ] Let Codex execute Day 1 implementation passes.


# M10 Ultra Preparation

- [x] Add autonomous build charter.
- [x] Add Codex start-here guide.
- [x] Add M10 master autonomous prompt.
- [x] Add pass sequence.
- [x] Add geometry and CRS contracts.
- [x] Add error taxonomy.
- [x] Add feature flag strategy.
- [x] Add model adapter guide.
- [x] Add QA/QC matching algorithm.
- [x] Add frontend state machine.
- [x] Add implementation ticket index and tickets.
- [x] Add API example payloads.
- [x] Add final pre-Codex checklist.

# Current Workbench UI

- [x] Replace the one-page workflow panel stack with a task-based workbench shell.
- [x] Add persistent project/AOI/dataset/layer context.
- [x] Move selected dataset details into a persistent inspector.
- [x] Deploy the shell refactor to Tower and run live browser smoke on port 1202.
- [x] Polish Data, Map and AI Labs workspaces.
- [x] Polish QA/QC and Exports workspaces.
- [x] Add selected-object inspector detail tabs for project, AOI, dataset, QA check, export and AI run context.
- [x] Improve map/dataset selection ergonomics from the workbench canvas and inspector.
- [x] Improve populated Data/Exports readability after a demo workflow run.
- [x] Improve live visual shell width, scroll behavior and Map workspace layout at 1280px.
- [x] Add export history filtering controls for long-running demo environments.
- [x] Add a safe export retention/cleanup command for demo environments.
- [x] Add a live dry-run maintenance smoke for demo export cleanup.
- [x] Add browser screenshot artifact automation for visual regression handoff.
- [x] Add backend error-envelope audit for expected user-error paths.
- [x] Expand golden datasets beyond the original single building QA fixture pair.
- [x] Add workbench visual polish pass for command bar, panel surfaces, empty states and mobile nav density.
- [x] Add map/result overlay ergonomics for active layer provenance and feature property summaries.
- [x] Add export/report handoff polish for artifact readiness, action grouping and export provenance.
- [x] Polish lightweight HTML project report readability, print styling and handoff sections.
- [x] Add Map empty-state quick actions for ready vector datasets.
- [x] Add Data catalog role-density polish for reference/candidate/source scanning.
- [x] Add Data catalog action polish for map, metadata, export and QA affordances.
- [x] Add QA/QC handoff polish for candidate/reference context and persisted results.
- [x] Add QA/QC metric card polish for precision, recall, F1, IoU and error counts.
- [x] Add mobile overflow hardening for workbench navigation, inspector and long QA identifiers.
- [x] Add QA/QC result filtering and density controls for long-running demo projects.
- [x] Add Overview workflow guidance for the V1 project -> data -> map -> QA/AI -> export path.
- [x] Audit populated demo workflow and tighten complete-state Overview guidance copy.
- [x] Make Overview workflow rail Map/Export clicks preserve useful dataset context.
- [x] Add latest handoff artifact cards to the Export Center for report, metadata and GeoJSON outputs.
- [x] Add QA/QC evidence drilldown for selected checks, false-positive/negative evidence and provenance JSON.
- [x] Add raster pipeline readiness and guardrail surfaces for metadata, CRS, preview, tile manifest and clip-AOI handoff.
- [x] Add useful default dataset context so Data, Map and Exports are immediately usable after project/demo load.
- [x] Make raster tile handoff to Detection Lab auto-select the configured YOLO run form.
- [x] Add AI Lab run-readiness checks for Detection and Segmentation before job submission.
- [x] Add AI Lab action guardrails so explicit fixture models are not exposed as normal operator runs.
- [x] Add persisted vector area selection from the Map workspace with bbox extract and GeoJSON download.
- [x] Persist map area selections as Export Center handoff artifacts.
- [x] Persist map area selections as reusable derived vector datasets indexed into `vector_features`.
- [x] Add Map workspace QA/QC shortcut for saved derived selection datasets.
- [x] Add Map workspace QA/QC evidence drilldown handoff for saved selection comparisons.
- [x] Persist QA/QC feature-level evidence for matches, false positives and false negatives.
- [x] Render persisted QA/QC feature-level evidence as Map workspace overlays.
- [x] Add safe local YOLO model env configuration helper for Unraid/Tower runtime activation.
- [x] Harden configured YOLO inference for single-band raster tiles and wrapped runtime errors.
- [x] Add operator-only YOLO dataset export and local training-smoke wrapper for real sample calibration.
- [x] Train/evaluate a small local GeoIntel building-detector smoke from the current operator samples and reject it because QA/QC did not improve.
- [x] Add operator-only tile-level YOLO dataset export with overlapping windows and deterministic negative tile retention.
- [x] Run tile-level training on Tower and accept/reject the resulting local model through the persisted QA/QC matrix.
- [x] Train/evaluate a YOLOv8s hard-negative local building-detector candidate on Tower and keep it inactive because hard-negative false positives remain.
- [x] Add an operator-facing local model catalog/activation workflow with SHA256, active model status and explicit threshold guidance.
- [x] Block silent local model asset auto-selection in Detection Lab.
- [x] Add structured raster tile manifest handoff into Detection Lab with linked preflight visibility.
- [x] Add full threshold calibration comparison UX so detection runs can compare candidate thresholds before promotion.
- [x] Add guided in-app detection calibration runner for explicit threshold sweeps.
- [x] Link guided calibration rows to the QA evidence map.
- [x] Add guided calibration summary export from the Detection Lab.
- [x] Allow the evidence bundle script to consume Detection Lab calibration summary exports.
- [x] Add a local browser-summary QA evidence bundle smoke using mocked canonical evidence responses.
- [x] Add a multi-AOI calibration evidence portfolio convention for model-review handoff.
- [x] Run the first live multi-AOI calibration evidence portfolio on Tower for Geel, Mol and Turnhout.
- [ ] Add more AOIs after the tile-level baseline so the next local model attempt is not limited to Geel/Mol/Turnhout.
- [ ] Add negative/background AOIs so the next tile dataset is not all positive tiles.