geointel/docs/CODEX_EXECUTION_PLAN.md

Codex Execution Plan — GeoIntel M1 Build

Core instruction

Build backend-first, then connect frontend. Do not start with visual polish. The project must become a working GeoAI Workbench foundation.

Pass 0 — Repo verification

Before coding:

• read README.md
• read docs/SPECIFICATION_FREEZE_M0.md
• read docs/V1_SCOPE_FREEZE.md
• read docs/SERVICE_ARCHITECTURE.md
• read docs/REPOSITORY_CONVENTIONS.md
• inspect current repo structure
• create/update docs/CODEX_EXECUTION_LOG.md

Output:

• execution log started
• no product scope changes

Pass 1 — Backend foundation

Implement:

• FastAPI app structure
• config management
• database session setup
• SQLAlchemy base
• health endpoint
• error handling
• repository/service folders
• pytest setup

Acceptance:

• backend starts
• health endpoint returns OK
• tests run

Do not implement GIS processing yet.

Pass 2 — Database schema foundation

Implement models and migrations if migration tooling is present:

• Project
• Area
• Dataset
• Layer
• AnalysisRun
• Detection
• Segmentation
• Metric
• QualityCheck
• Export
• JobLog or AnalysisLog

Acceptance:

• tables can be created
• model relationships work
• basic repository tests pass

Pass 3 — Project and area API

Implement:

• project CRUD
• area CRUD
• GeoJSON polygon input
• area/perimeter calculation using metric CRS
• validation for invalid geometry

Acceptance:

• create project
• create area
• retrieve project with areas
• tests for simple polygon area

Pass 4 — Dataset Manager API

Implement:

• upload endpoint
• storage service
• dataset records
• file checksum
• type detection
• metadata endpoint

Acceptance:

• upload vector fixture
• upload raster fixture if available
• dataset metadata stored
• unsupported file returns clear error

Pass 5 — Vector foundation

Implement:

• GeoJSON import
• zipped shapefile import if feasible
• CRS detection
• geometry validation
• clipping by area
• summary metrics

Acceptance:

• vector fixture imported
• vector clipped by test area
• area/length stats correct

Pass 6 — Raster foundation

Implement:

• raster metadata extraction
• raster bounds/CRS/resolution/bands
• raster clip by area when CRS exists
• simple histogram/statistics
• tile job records or actual tile generation

Acceptance:

• raster fixture metadata read
• missing CRS warning works
• clip operation returns artifact path or clear unsupported message

Pass 7 — Reference layer provider foundation

Implement:

• provider interface
• local fixture provider
• configurable GRB WFS provider shell
• caching reference layer as Dataset/Layer

Acceptance:

• fixture building reference layer loads
• provider output normalized
• cached layer can be used by QA service

Pass 8 — Detection pipeline foundation

Implement:

• DetectionService
• DevelopmentDetectionProvider with deterministic fixture output
• YoloDetectionProvider interface/shell if dependency not ready
• detection analysis run lifecycle
• detection geometry persistence
• GeoJSON export

Acceptance:

• run detection on fixture/project
• detections are persisted
• detections appear as layer output
• export returns GeoJSON

Important:

• Use development provider only as a temporary provider, not as fake final logic.
• Keep provider interface ready for YOLO.

Pass 9 — QA/QC engine

Implement:

• IoU calculation
• matching algorithm
• precision/recall/F1
• false positive/false negative layers
• quality check persistence

Acceptance:

• unit tests for IoU
• unit tests for matching
• QA run compares detection fixture to reference fixture
• metrics persisted and returned

Pass 10 — Segmentation foundation

Implement:

• segmentation analysis run lifecycle
• development segmentation provider
• mask artifact record
• polygon output if simple fixture allows

Acceptance:

• segmentation run can be created
• segmentation result can be listed/exported

Pass 11 — Frontend foundation

Implement:

• React app shell
• routing
• API client
• project list/create page
• project workspace page
• status/error/empty components

Acceptance:

• frontend starts
• user can create/open project through API

Pass 12 — Dataset and Map UI

Implement:

• Dataset Manager page
• Map Workbench page
• layer manager
• display vector outputs
• show dataset metadata

Acceptance:

• user can upload/import dataset
• user can see layer on map or at least its extent/feature list if map library setup is incomplete

Pass 13 — Detection and QA UI

Implement:

• Detection Lab page
• run detection with provider selector
• show detections
• QA/QC Lab page
• run QA against reference layer
• show metrics and findings

Acceptance:

• Demo 1 can be executed end-to-end from UI using fixtures/development provider

Pass 14 — Export UI and workflow polish

Implement:

• Exports page
• export history
• GeoJSON download
• run summary view
• useful empty states

Acceptance:

• user can download detection/QA output

Pass 15 — Documentation and handoff

Update:

• docs/TODO.md
• docs/CODEX_EXECUTION_LOG.md
• README quickstart
• known limitations

Run:

• backend tests
• frontend typecheck/build if available

Final response must include:

• what was built
• tests run
• what remains open
• exact next pass recommendation

Absolute restrictions

• Do not remove documentation.
• Do not implement unrelated features.
• Do not add authentication.
• Do not add payment/sharing/multi-user.
• Do not hide broken endpoints behind UI-only mock data.
• Do not calculate metric geometry on EPSG:4326.
• Do not export misleading geospatial outputs from non-georeferenced rasters.