geointel/docs/12-build-control/BUILD_SEQUENCE_LOCK.md

Build Sequence Lock

This file freezes the order in which Codex should build GeoIntel V1. Codex can split passes into smaller chunks, but it must not reorder major dependencies.

Phase 0 — Repository Verification

• Verify folder structure.
• Verify documentation set exists.
• Verify .env.example and docker-compose exist.
• Verify scripts are executable or document how to run them.
• Verify fixtures are valid GeoJSON.

Exit criteria:

• all preflight scripts run or have clear remediation notes.

Phase 1 — Backend Foundation

• FastAPI app shell.
• Health endpoint.
• Settings/config loader.
• Structured error response model.
• CORS configured for local frontend.
• Logging baseline.

Exit criteria:

• backend imports successfully.
• /health returns service status.
• config is read from environment.

Phase 2 — Database Foundation

• SQLAlchemy or SQLModel models.
• Alembic migrations.
• PostGIS extension migration.
• project, area, dataset, analysis_run base tables.
• geometry storage strategy implemented.

Exit criteria:

• migrations run against PostGIS.
• seed script creates one project and one area.

Phase 3 — Project, Area and Dataset APIs

• CRUD for projects.
• CRUD for areas.
• dataset upload endpoint.
• metadata extraction queue boundary.
• file storage path convention.

Exit criteria:

• OpenAPI docs expose complete endpoints.
• API tests pass for create/list/read flows.

Phase 4 — Geospatial Metadata

• vector metadata extraction.
• raster metadata extraction.
• CRS validation.
• bounds extraction.
• geometry validation.

Exit criteria:

• sample GeoJSON returns feature count, bounds and CRS status.
• sample raster placeholder or documented stub returns safe metadata response.

Phase 5 — Frontend Shell

• React app.
• routing.
• layout.
• API client.
• project list.
• project workspace.
• map workspace placeholder.

Exit criteria:

• frontend starts.
• health check visible.
• project list loads from API.

Phase 6 — Map and Layer Foundation

• MapLibre map.
• draw/select area.
• layer manager.
• vector layer rendering.
• dataset detail panel.

Exit criteria:

• fixture GeoJSON renders on map.
• drawn area can be saved through API.

Phase 7 — QA/QC Foundation

• load predicted and reference polygons.
• compute IoU-based matching.
• compute precision, recall and F1.
• create QA result payload.
• render QA dashboard.

Exit criteria:

• fixture QA returns deterministic metrics.
• false positives and false negatives are exported as GeoJSON.

Phase 8 — Detection Interface Boundary

• detection run model.
• detection service interface.
• model registry stub.
• deterministic fixture-based inference fallback.
• later YOLO integration boundary.

Exit criteria:

• detection run can produce geospatial detections using fixture mode.
• output is stored and visible as layer.

Phase 9 — Export Pipeline

• export GeoJSON.
• export metrics JSON.
• prepare report shell.
• export provenance metadata.

Exit criteria:

• user can download GeoJSON output from UI.

Phase 10 — Stabilization

• smoke tests.
• contract tests.
• docs update.
• changelog.
• known limitations.

Exit criteria:

• V1 vertical slice is demonstrable end-to-end.