geointel/docs/workflows/GOLDEN_PATHS.md

Golden Paths

Golden paths are protected workflows. Every major Codex pass must avoid breaking them.

Golden Path 1 — Project Area Dataset Foundation

Goal: prove that the app can create a geospatial workspace.

Steps:

1. Create project.
2. Create an Area from GeoJSON.
3. Upload/register a vector dataset.
4. Extract metadata.
5. Persist dataset and geometry metadata.
6. Display project, area and dataset in frontend.

Pass criteria:

• project exists via API;
• area geometry validates;
• dataset reaches READY or honest failure state;
• frontend can show the state.

Golden Path 2 — Reference Building QA

Goal: prove core GeoAI value without requiring real model inference yet.

Steps:

1. Load demo reference buildings.
2. Load demo predicted buildings.
3. Run matching algorithm.
4. Produce precision, recall, F1 and IoU summary.
5. Store QA run.
6. Export matched/unmatched features as GeoJSON.

Pass criteria:

• metrics are deterministic on fixtures;
• thresholds are configurable;
• false positives/false negatives are visible;
• export is valid GeoJSON.

Golden Path 3 — Raster Metadata and Tiling Readiness

Goal: prove raster handling foundation.

Steps:

1. Register/upload GeoTIFF.
2. Extract metadata.
3. Validate CRS/transform.
4. Generate tile manifest without necessarily running AI.
5. Store tile parameters.

Pass criteria:

• metadata is persisted;
• tile count is deterministic;
• georeferencing is preserved;
• unsupported rasters fail honestly.

Golden Path 4 — Detection Result Lifecycle

Goal: prove detection outputs can travel through the system.

Steps:

1. Create or import detection run.
2. Store detections with class/confidence/geometry.
3. Render detections as layer.
4. Run QA against reference.
5. Export detections.

Pass criteria:

• no frontend-only detections;
• every detection belongs to analysis run;
• geometries are valid;
• export works.

Golden Path 5 — V1 Recruiter Demo

Goal: show portfolio value.

Narrative:

GeoIntel loads a Kempen area, compares predicted building detections with reference building polygons, reports QA metrics, shows spatial errors and exports usable GIS output.

Minimum demo artifacts:

• map layer with reference buildings;
• map layer with predicted detections;
• QA metrics panel;
• unmatched features layer;
• GeoJSON export;
• concise explanation of methods and limitations.