# 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.