# Final Codex Pass Sequence

Codex must execute these passes in order. Do not skip ahead unless the previous pass is complete and smoke-checked.

## Pass 0 — Repo audit and bootstrap

Goal: confirm the repo can be used as an implementation workspace.

Deliverables:

- confirm folder structure;
- install/dependency plan selected;
- create missing backend/frontend scaffolding only if absent;
- no product feature work yet;
- run docs smoke scripts.

Exit criteria:

- `CODEX_START.md` is acknowledged;
- canonical docs are read;
- no conflicting start path remains unaddressed in notes.

## Pass 1 — Backend application foundation

Goal: create a FastAPI app that imports and serves health/status endpoints.

Deliverables:

- `backend/app/main.py`;
- settings/config module;
- API router structure;
- health endpoint;
- error envelope helper;
- minimal tests.

Exit criteria:

- backend imports successfully;
- health endpoint test passes;
- no database required yet.

## Pass 2 — Database and domain foundation

Goal: establish SQLAlchemy/Alembic/PostGIS-ready domain models.

Deliverables:

- DB config;
- migration skeleton;
- models for Project, Area, Dataset, AnalysisRun, Detection, Metric, Export;
- schemas for request/response;
- geometry storage strategy documented in code comments and docs.

Exit criteria:

- migrations can be generated/applied in local environment;
- models match canonical domain docs;
- no geometry stored as arbitrary string when PostGIS type is available.

## Pass 3 — Project and Area API

Goal: implement the first user-managed domain objects.

Deliverables:

- project CRUD;
- area CRUD;
- geometry validation;
- area calculation;
- API tests;
- response envelope compliance.

Exit criteria:

- create/list/read project works;
- create/list/read area works;
- invalid geometry returns controlled error.

## Pass 4 — Dataset manager foundation

Goal: register datasets and extract basic metadata.

Deliverables:

- dataset upload/registration endpoint;
- metadata schema;
- storage path convention;
- fixture registration path;
- dataset state machine implemented.

Exit criteria:

- fixture vector dataset can be registered;
- dataset moves through valid states;
- failed validation is explicit.

## Pass 5 — Vector processing core

Goal: load reference polygons and predicted detection polygons.

Deliverables:

- GeoJSON import;
- geometry normalization;
- CRS handling;
- feature count and bounds metrics;
- persistence of reference and predicted layers.

Exit criteria:

- reference buildings fixture imports;
- predicted buildings fixture imports;
- invalid GeoJSON is rejected safely.

## Pass 6 — QA/QC engine foundation

Goal: compare predicted detections against reference polygons.

Deliverables:

- IoU/overlap matching;
- precision, recall, F1;
- false positive/false negative outputs;
- quality check records;
- tests with demo fixtures.

Exit criteria:

- expected demo metrics are reproduced or documented;
- algorithm is deterministic;
- matching thresholds are configurable but defaulted.

## Pass 7 — GeoJSON export

Goal: export geospatial outputs from the system.

Deliverables:

- export endpoint;
- export records;
- GeoJSON FeatureCollection output;
- export validation;
- smoke test.

Exit criteria:

- detections export as valid GeoJSON;
- QA/QC outputs can be exported;
- no broken geometry emitted.

## Pass 8 — Frontend workbench shell

Goal: create a minimal but coherent UI.

Deliverables:

- React/TypeScript app shell;
- route structure;
- project list/detail;
- map workbench placeholder with layer panel;
- API client;
- loading/error/empty states.

Exit criteria:

- frontend builds;
- health/status can be displayed;
- no hardcoded permanent fake data except clearly marked demo fixtures.

## Pass 9 — Map and metrics integration

Goal: show the vertical slice visually.

Deliverables:

- render area/reference/prediction layers;
- metrics panel;
- QA/QC result cards;
- export action;
- basic style guide compliance.

Exit criteria:

- demo Geel workflow can be clicked through;
- layer visibility/opacity works at minimum level;
- UI does not obscure the map or results.

## Pass 10 — Stabilization and release candidate

Goal: make the first vertical slice releasable.

Deliverables:

- smoke tests;
- docs update;
- known limitations;
- changelog;
- run instructions;
- regression checklist.

Exit criteria:

- backend tests pass;
- frontend build passes;
- demo workflow documented;
- no architecture invariant violated.