207 lines
4.4 KiB
Markdown
207 lines
4.4 KiB
Markdown
# 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.
|