Initial GeoIntel V1 foundation
This commit is contained in:
Codex
@@ -0,0 +1,147 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Codex Decision Boundaries
|
||||
|
||||
This document defines where Codex has freedom and where it must not decide alone.
|
||||
|
||||
## Codex Can Decide
|
||||
|
||||
- internal helper function names
|
||||
- folder organization within already approved domains
|
||||
- UI microcopy that clarifies state
|
||||
- additional tests
|
||||
- stricter validation when compatible with contracts
|
||||
- small refactors that reduce duplication
|
||||
- dependency minor versions when compatible
|
||||
- CSS implementation details
|
||||
|
||||
## Codex Must Follow Existing Specs
|
||||
|
||||
- primary tech stack
|
||||
- FastAPI backend
|
||||
- React frontend
|
||||
- PostGIS database
|
||||
- GRB-first reference strategy
|
||||
- status enums
|
||||
- API envelopes
|
||||
- CRS calculation rules
|
||||
- QA/QC formulas
|
||||
- V1 scope boundaries
|
||||
- build sequence
|
||||
|
||||
## Codex Must Ask or Stop
|
||||
|
||||
- replacing FastAPI, PostGIS, React or MapLibre
|
||||
- changing project direction from GeoAI Workbench
|
||||
- adding authentication
|
||||
- adding paid services
|
||||
- changing reference data strategy
|
||||
- changing scoring/math definitions
|
||||
- presenting fixture output as real AI
|
||||
- introducing non-deterministic tests
|
||||
- removing docs/tests to make builds pass
|
||||
|
||||
## Improvement Rule
|
||||
|
||||
If Codex sees a better approach, it may implement it only when:
|
||||
|
||||
1. it is backward compatible with specs
|
||||
2. it improves correctness, reliability or clarity
|
||||
3. it updates docs and tests
|
||||
4. it does not expand V1 scope
|
||||
|
||||
If not, document it as a proposal in `docs/PROPOSED_IMPROVEMENTS.md`.
|
||||
@@ -0,0 +1,89 @@
|
||||
# M7 Implementation Control Layer
|
||||
|
||||
This layer exists to keep Codex productive without allowing it to improvise core architecture.
|
||||
|
||||
## Purpose
|
||||
|
||||
M7 adds strict execution control around the existing GeoIntel specifications. It defines how Codex should sequence work, how each pass should prove completion, which traps to avoid, and when it is allowed to improve the design.
|
||||
|
||||
## Operating Principle
|
||||
|
||||
Codex may improve implementation quality, developer experience, robustness, performance and UX clarity, but it may not silently change product direction, data model semantics, analysis definitions, geospatial meaning or API contracts.
|
||||
|
||||
## Build Priorities
|
||||
|
||||
1. Keep the vertical slice working at all times.
|
||||
2. Build backend contracts before frontend polish.
|
||||
3. Prefer small complete modules over broad incomplete scaffolding.
|
||||
4. Every result must be reproducible from fixtures or documented sample data.
|
||||
5. Every analysis output must retain source, parameters, units and assumptions.
|
||||
6. Every geospatial geometry must carry CRS awareness.
|
||||
7. Every long-running process must expose status, errors and recoverability.
|
||||
|
||||
## Mandatory Per-Pass Output
|
||||
|
||||
At the end of every Codex pass, update or create:
|
||||
|
||||
- `CHANGELOG.md`
|
||||
- `docs/BUILD_STATUS.md`
|
||||
- relevant TODO checkboxes
|
||||
- test notes
|
||||
- known limitations
|
||||
- next recommended pass
|
||||
|
||||
If a pass changes API contracts, update `contracts/api/` and all affected frontend service calls.
|
||||
|
||||
If a pass changes database models, update migrations, schema docs and seed data.
|
||||
|
||||
If a pass changes analysis logic, update analysis specifications, tests and expected fixtures.
|
||||
|
||||
## Allowed Improvements
|
||||
|
||||
Codex may add:
|
||||
|
||||
- better validation
|
||||
- better error messages
|
||||
- safer defaults
|
||||
- clearer UI states
|
||||
- test fixtures
|
||||
- helper utilities
|
||||
- small performance improvements
|
||||
- developer scripts
|
||||
- documentation clarifications
|
||||
|
||||
Codex may not add without explicit approval:
|
||||
|
||||
- multi-user auth
|
||||
- paid external services
|
||||
- unrelated AI chat features
|
||||
- unrelated dashboards
|
||||
- LiDAR production implementation before V1 slice
|
||||
- training studio before detection and QA/QC are stable
|
||||
- new primary data sources that conflict with GRB-first strategy
|
||||
|
||||
## Stop Conditions
|
||||
|
||||
Codex must stop and report instead of continuing if:
|
||||
|
||||
- a core specification conflicts with another specification
|
||||
- a required dependency cannot be installed
|
||||
- tests fail for reasons that require product decision changes
|
||||
- geospatial output cannot be tied to CRS or source metadata
|
||||
- generated outputs would be misleading or scientifically invalid
|
||||
|
||||
## M7 Completion Target
|
||||
|
||||
The repository is ready for autonomous implementation when Codex can execute:
|
||||
|
||||
1. preflight checks
|
||||
2. backend foundation
|
||||
3. database foundation
|
||||
4. dataset upload and metadata
|
||||
5. map workspace
|
||||
6. raster/vector preview
|
||||
7. demo detection stub or real YOLO integration boundary
|
||||
8. QA/QC fixture comparison
|
||||
9. GeoJSON export
|
||||
10. smoke tests
|
||||
|
||||
without needing manual architecture decisions.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Module Completion Matrix
|
||||
|
||||
This matrix defines what counts as complete for each V1 module.
|
||||
|
||||
| Module | Backend | Frontend | Tests | Docs | V1 Complete When |
|
||||
|---|---|---|---|---|---|
|
||||
| Project Manager | CRUD endpoints, models | list/detail/create | API tests | API + UI docs | User can create/open project |
|
||||
| Area Manager | geometry validation, save area | draw/save/list areas | geometry fixture tests | geospatial rules updated | User can draw and persist polygon |
|
||||
| Dataset Manager | upload, metadata, storage | upload form, dataset table | upload/metadata tests | storage + data docs | Dataset can be uploaded and inspected |
|
||||
| Raster Lab | metadata boundary, clip/preview stubs | metadata panel, preview state | metadata tests | raster spec | Raster dataset has readable metadata |
|
||||
| Vector Lab | GeoJSON import, feature count, bounds | map overlay, details | fixture render/API tests | vector spec | Vector layer renders and can be inspected |
|
||||
| Detection Lab | analysis run + fixture inference | run form, output layer | deterministic fixture tests | detection spec | Fixture detection output is stored and shown |
|
||||
| Segmentation Lab | analysis run boundary | planned UI state | contract tests | segmentation spec | V1 may show prepared state unless detection is stable |
|
||||
| QA/QC Lab | IoU, precision, recall, F1 | metrics panel, error layers | golden QA tests | QA spec | Fixture predictions compare to reference |
|
||||
| Export Center | GeoJSON/metrics export | download buttons | export tests | export spec | User downloads GeoJSON result |
|
||||
| Build Status | changelog/status docs | optional UI link | smoke docs test | build status | Status remains truthful |
|
||||
Reference in New Issue
Block a user