Initial GeoIntel V1 foundation
This commit is contained in:
Codex
@@ -0,0 +1,91 @@
|
||||
# M9 API Validation Examples
|
||||
|
||||
All errors must use the documented API envelope.
|
||||
|
||||
## Invalid Project Name
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{ "name": "" }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"data": null,
|
||||
"error": {
|
||||
"code": "validation_error",
|
||||
"message": "Project name is required.",
|
||||
"details": { "field": "name" }
|
||||
},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Invalid GeoJSON Polygon
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"data": null,
|
||||
"error": {
|
||||
"code": "invalid_geometry",
|
||||
"message": "Area geometry must be a valid Polygon or MultiPolygon in EPSG:4326.",
|
||||
"details": {
|
||||
"reason": "self_intersection"
|
||||
}
|
||||
},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Unsupported Dataset Type
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"data": null,
|
||||
"error": {
|
||||
"code": "unsupported_dataset_type",
|
||||
"message": "This file type is not supported in V1.",
|
||||
"details": {
|
||||
"allowed_extensions": [".geojson", ".json", ".tif", ".tiff", ".gpkg"]
|
||||
}
|
||||
},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
## External Source Unavailable
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"data": null,
|
||||
"error": {
|
||||
"code": "external_service_unavailable",
|
||||
"message": "The GRB service is unavailable. Use cached data or retry later.",
|
||||
"details": { "source": "GRB" }
|
||||
},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Job Failed
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"job_id": "uuid",
|
||||
"status": "failed",
|
||||
"error_code": "model_not_available",
|
||||
"error_message": "No compatible detection model is configured."
|
||||
},
|
||||
"error": null,
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,89 @@
|
||||
# M9 Autonomous Build Doctrine
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines how Codex should behave when building GeoIntel with minimal human intervention.
|
||||
|
||||
## Build Philosophy
|
||||
|
||||
GeoIntel must grow like a professional engineering system:
|
||||
|
||||
1. Contracts first.
|
||||
2. Backend services second.
|
||||
3. Frontend integration third.
|
||||
4. AI pipelines only after stable data flow.
|
||||
5. QA/QC after outputs exist.
|
||||
6. Polish only after functionality is testable.
|
||||
|
||||
## Strictness Levels
|
||||
|
||||
### Frozen
|
||||
|
||||
Codex must not change these:
|
||||
|
||||
- FastAPI backend.
|
||||
- React TypeScript frontend.
|
||||
- PostgreSQL/PostGIS database.
|
||||
- Docker Compose local stack.
|
||||
- Project/Area/Dataset/Analysis domain model.
|
||||
- API response envelope.
|
||||
- Storage root conventions.
|
||||
- V1 scope.
|
||||
|
||||
### Guided
|
||||
|
||||
Codex may choose implementation details within these:
|
||||
|
||||
- exact Python package split,
|
||||
- React component granularity,
|
||||
- internal helper names,
|
||||
- validation library patterns,
|
||||
- test fixture organization,
|
||||
- queue abstraction internals.
|
||||
|
||||
### Open Improvement Area
|
||||
|
||||
Codex may improve freely if documented:
|
||||
|
||||
- UI microcopy,
|
||||
- accessibility,
|
||||
- loading states,
|
||||
- logging clarity,
|
||||
- test coverage,
|
||||
- developer command quality,
|
||||
- type safety.
|
||||
|
||||
## Self-Driving Loop
|
||||
|
||||
Every build pass must follow this loop:
|
||||
|
||||
1. Read relevant specs.
|
||||
2. Identify scope for the pass.
|
||||
3. Implement the smallest complete vertical slice.
|
||||
4. Run tests/lint/type checks where available.
|
||||
5. Update execution log.
|
||||
6. Update build status.
|
||||
7. List next pass.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
Do not:
|
||||
|
||||
- create huge untested code dumps,
|
||||
- implement UI without API contracts,
|
||||
- invent fake geospatial values,
|
||||
- build YOLO UI before dataset IO works,
|
||||
- create multiple competing state stores,
|
||||
- store geospatial data as plain strings when PostGIS geometry is required,
|
||||
- ignore CRS handling,
|
||||
- call external services without adapter boundaries.
|
||||
|
||||
## Autonomy Boundary
|
||||
|
||||
Codex can keep working independently as long as:
|
||||
|
||||
- tests are passing or failures are honestly documented,
|
||||
- no frozen decision is changed,
|
||||
- V1 scope is preserved,
|
||||
- every new file belongs to an approved module,
|
||||
- build logs are updated.
|
||||
@@ -0,0 +1,101 @@
|
||||
# M9 Build Blockers and Recovery
|
||||
|
||||
## Database connection failure
|
||||
|
||||
Symptoms:
|
||||
|
||||
- backend cannot connect to PostgreSQL,
|
||||
- migrations fail,
|
||||
- PostGIS extension missing.
|
||||
|
||||
Recovery:
|
||||
|
||||
1. Check Docker Compose service names.
|
||||
2. Check environment variables.
|
||||
3. Confirm database is reachable from backend container or local process.
|
||||
4. Run a minimal connection test.
|
||||
5. Do not replace PostGIS with SQLite except for explicitly isolated unit tests.
|
||||
|
||||
## PostGIS geometry error
|
||||
|
||||
Symptoms:
|
||||
|
||||
- invalid geometry,
|
||||
- SRID missing,
|
||||
- geometry column cannot be created.
|
||||
|
||||
Recovery:
|
||||
|
||||
1. Store all app geometry in EPSG:4326 unless a processing-specific CRS is required.
|
||||
2. Validate GeoJSON before persistence.
|
||||
3. Use Shapely for geometry validation.
|
||||
4. Use PostGIS geometry column for persistent area/reference features.
|
||||
5. Document any CRS transformation.
|
||||
|
||||
## Frontend API mismatch
|
||||
|
||||
Symptoms:
|
||||
|
||||
- UI expects raw data but API returns envelope,
|
||||
- errors not shown,
|
||||
- undefined data states.
|
||||
|
||||
Recovery:
|
||||
|
||||
1. Update frontend API client, not individual components.
|
||||
2. Normalize envelope handling centrally.
|
||||
3. Ensure every component handles loading, empty, error and ready states.
|
||||
|
||||
## Dependency installation failure
|
||||
|
||||
Symptoms:
|
||||
|
||||
- GDAL/Rasterio install errors,
|
||||
- PyTorch package issue,
|
||||
- platform binary mismatch.
|
||||
|
||||
Recovery:
|
||||
|
||||
1. Do not remove the feature from docs.
|
||||
2. Add dependency note to `docs/DEPENDENCY_LOCK_PLAN.md`.
|
||||
3. Implement interfaces and tests around pure-Python parts first.
|
||||
4. Defer heavy binary package execution if needed, but leave adapter boundaries.
|
||||
|
||||
## External data unavailable
|
||||
|
||||
Symptoms:
|
||||
|
||||
- WFS unavailable,
|
||||
- Sentinel catalog unavailable,
|
||||
- credentials missing.
|
||||
|
||||
Recovery:
|
||||
|
||||
1. Use demo fixtures.
|
||||
2. Keep adapter disabled but present.
|
||||
3. Return explicit `external_service_unavailable` status.
|
||||
4. Do not fake that live data was fetched.
|
||||
|
||||
## AI model unavailable
|
||||
|
||||
Symptoms:
|
||||
|
||||
- YOLO weights missing,
|
||||
- SAM unavailable,
|
||||
- GPU unavailable.
|
||||
|
||||
Recovery:
|
||||
|
||||
1. Build model registry and adapter interface.
|
||||
2. Add CPU-safe mock inference only if marked as demo mode.
|
||||
3. Keep output schema identical to real inference.
|
||||
4. Do not present demo inference as production inference.
|
||||
|
||||
## Test failures
|
||||
|
||||
Recovery:
|
||||
|
||||
1. Fix tests if implementation is wrong.
|
||||
2. Fix implementation if test reflects contract.
|
||||
3. Update specs only if they are clearly inconsistent.
|
||||
4. Document unresolved failures in execution log.
|
||||
@@ -0,0 +1,110 @@
|
||||
# M9 Detailed Data Contracts
|
||||
|
||||
## Project
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Geel Building Detection Demo",
|
||||
"description": "Building detection and QA against reference features.",
|
||||
"region": "Kempen",
|
||||
"created_at": "2026-06-11T12:00:00Z",
|
||||
"updated_at": "2026-06-11T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- name is required,
|
||||
- region defaults to Kempen,
|
||||
- description optional.
|
||||
|
||||
## Area
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"project_id": "uuid",
|
||||
"name": "Geel center test area",
|
||||
"geometry": { "type": "Polygon", "coordinates": [] },
|
||||
"crs": "EPSG:4326",
|
||||
"area_m2": 12345.67,
|
||||
"bounds": [4.98, 51.15, 5.02, 51.18]
|
||||
}
|
||||
```
|
||||
|
||||
Validation:
|
||||
|
||||
- geometry must be Polygon or MultiPolygon,
|
||||
- geometry must be valid,
|
||||
- geometry must not be empty,
|
||||
- area_m2 must be computed server-side,
|
||||
- CRS is EPSG:4326 for API IO unless explicitly documented.
|
||||
|
||||
## Dataset
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"project_id": "uuid",
|
||||
"name": "reference_buildings.geojson",
|
||||
"dataset_type": "vector",
|
||||
"source_mode": "demo",
|
||||
"source_name": "fixture",
|
||||
"storage_path": "storage/projects/.../raw/reference_buildings.geojson",
|
||||
"status": "uploaded|processing|ready|failed",
|
||||
"crs": "EPSG:4326",
|
||||
"bounds": [4.98, 51.15, 5.02, 51.18],
|
||||
"feature_count": 100,
|
||||
"metadata": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Analysis Run
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"project_id": "uuid",
|
||||
"area_id": "uuid",
|
||||
"analysis_type": "object_detection|segmentation|qaqc|raster_metadata|vector_metadata",
|
||||
"status": "queued|running|completed|failed|cancelled",
|
||||
"parameters": {},
|
||||
"started_at": null,
|
||||
"finished_at": null,
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
## Detection Feature
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"analysis_run_id": "uuid",
|
||||
"class_name": "building",
|
||||
"confidence": 0.91,
|
||||
"geometry": { "type": "Polygon", "coordinates": [] },
|
||||
"bbox": [4.99, 51.16, 4.991, 51.161],
|
||||
"source_tile": "tile_001.tif",
|
||||
"metadata": {}
|
||||
}
|
||||
```
|
||||
|
||||
## QA/QC Result
|
||||
|
||||
```json
|
||||
{
|
||||
"analysis_run_id": "uuid",
|
||||
"reference_dataset_id": "uuid",
|
||||
"predicted_dataset_id": "uuid",
|
||||
"match_threshold_iou": 0.5,
|
||||
"precision": 0.94,
|
||||
"recall": 0.91,
|
||||
"f1": 0.925,
|
||||
"true_positives": 94,
|
||||
"false_positives": 6,
|
||||
"false_negatives": 9,
|
||||
"findings": []
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,46 @@
|
||||
# M9 Final Pre-Code Checklist
|
||||
|
||||
Before starting a long Codex build session, verify:
|
||||
|
||||
## Repository
|
||||
|
||||
- [ ] Full zip extracted cleanly.
|
||||
- [ ] Git initialized.
|
||||
- [ ] Initial commit made before Codex changes.
|
||||
- [ ] `.env.example` exists.
|
||||
- [ ] Docker Compose file exists.
|
||||
- [ ] README explains the project.
|
||||
|
||||
## Codex Input
|
||||
|
||||
- [ ] Master prompt available.
|
||||
- [ ] Build order available.
|
||||
- [ ] Definition of Done available.
|
||||
- [ ] Scorecards available.
|
||||
- [ ] Failure recovery available.
|
||||
|
||||
## Scope
|
||||
|
||||
- [ ] V1 scope freeze read.
|
||||
- [ ] No LiDAR in first pass.
|
||||
- [ ] No training studio in first pass.
|
||||
- [ ] No QGIS plugin in first pass.
|
||||
- [ ] No advanced Sentinel implementation in first pass.
|
||||
|
||||
## Expected First Output
|
||||
|
||||
- [ ] Pass 0 audit.
|
||||
- [ ] Execution log.
|
||||
- [ ] Build status.
|
||||
- [ ] Gap report.
|
||||
|
||||
## Local Environment
|
||||
|
||||
- [ ] Docker available.
|
||||
- [ ] Node available.
|
||||
- [ ] Python available.
|
||||
- [ ] PostgreSQL/PostGIS preferably via Docker.
|
||||
|
||||
## Human Intervention Rules
|
||||
|
||||
Only intervene if Codex asks to change a frozen decision or cannot proceed due to environment failure.
|
||||
@@ -0,0 +1,54 @@
|
||||
# M9 Gap-to-Task Conversion Rules
|
||||
|
||||
When Codex finds a gap, it must convert it into an actionable task instead of leaving vague notes.
|
||||
|
||||
## Task Format
|
||||
|
||||
```md
|
||||
### TASK-ID: Short title
|
||||
|
||||
Type: backend | frontend | docs | test | devops | data | ai
|
||||
Priority: P0 | P1 | P2 | P3
|
||||
Status: open | in_progress | done | blocked
|
||||
Owner: Codex
|
||||
|
||||
Context:
|
||||
...
|
||||
|
||||
Required changes:
|
||||
- ...
|
||||
|
||||
Acceptance criteria:
|
||||
- [ ] ...
|
||||
|
||||
Validation commands:
|
||||
- ...
|
||||
|
||||
Blocked by:
|
||||
- none or exact blocker
|
||||
```
|
||||
|
||||
## Priority Rules
|
||||
|
||||
### P0
|
||||
|
||||
Blocks app startup, database, API envelope, project/area/dataset foundation.
|
||||
|
||||
### P1
|
||||
|
||||
Blocks V1 core workflow but not app startup.
|
||||
|
||||
### P2
|
||||
|
||||
Improves quality, tests, UX, docs.
|
||||
|
||||
### P3
|
||||
|
||||
Nice-to-have or future extension.
|
||||
|
||||
## Gap Handling
|
||||
|
||||
- If gap is architecture-related: update docs before code.
|
||||
- If gap is implementation-related: create ticket and implement if in current pass.
|
||||
- If gap is dependency-related: document in dependency plan and add fallback interface.
|
||||
- If gap is scope expansion: move to proposed improvements.
|
||||
@@ -0,0 +1,90 @@
|
||||
# M9 Geospatial Edge Cases
|
||||
|
||||
Codex must account for these cases early to avoid later rewrites.
|
||||
|
||||
## Invalid polygon
|
||||
|
||||
Examples:
|
||||
|
||||
- self-intersection,
|
||||
- unclosed ring,
|
||||
- empty coordinates,
|
||||
- wrong coordinate nesting.
|
||||
|
||||
Required behavior:
|
||||
|
||||
- reject with validation error,
|
||||
- return specific message,
|
||||
- do not persist.
|
||||
|
||||
## MultiPolygon
|
||||
|
||||
Required behavior:
|
||||
|
||||
- accept for areas and vector features,
|
||||
- compute total area across all parts,
|
||||
- display as a single layer.
|
||||
|
||||
## CRS mismatch
|
||||
|
||||
Scenario:
|
||||
|
||||
- reference data is EPSG:31370,
|
||||
- API uses EPSG:4326,
|
||||
- raster processing may use native CRS.
|
||||
|
||||
Required behavior:
|
||||
|
||||
- store original CRS in dataset metadata,
|
||||
- transform API geometries to EPSG:4326 for frontend,
|
||||
- use projected CRS for area/length calculations when needed,
|
||||
- document transformations.
|
||||
|
||||
## Very large file
|
||||
|
||||
Required behavior:
|
||||
|
||||
- reject files above configured limit with clear error,
|
||||
- do not load huge files into memory at once,
|
||||
- expose future chunking/tile strategy.
|
||||
|
||||
## Raster without georeference
|
||||
|
||||
Required behavior:
|
||||
|
||||
- accept only as non-georeferenced image if supported,
|
||||
- mark geospatial operations unavailable,
|
||||
- do not pretend map alignment exists.
|
||||
|
||||
## Feature outside selected area
|
||||
|
||||
Required behavior:
|
||||
|
||||
- clip if operation requested,
|
||||
- otherwise keep original and display warning if used for area analysis.
|
||||
|
||||
## Geometry collection
|
||||
|
||||
Required behavior:
|
||||
|
||||
- reject for V1 unless explicitly converted,
|
||||
- explain supported geometry types.
|
||||
|
||||
## Zero-area feature
|
||||
|
||||
Required behavior:
|
||||
|
||||
- keep for line/point layers,
|
||||
- reject or ignore for polygon-area metrics,
|
||||
- record warning in analysis result.
|
||||
|
||||
## Duplicate features
|
||||
|
||||
Required behavior:
|
||||
|
||||
- do not automatically delete without audit trail,
|
||||
- expose duplicate count in data quality metadata.
|
||||
|
||||
## Antimeridian/global edge cases
|
||||
|
||||
Not relevant for Kempen V1. Document as out of scope.
|
||||
@@ -0,0 +1,59 @@
|
||||
# M9 Implementation Review Script
|
||||
|
||||
Use this manual review script after Codex produces a build.
|
||||
|
||||
## 1. Repository Hygiene
|
||||
|
||||
- [ ] No random root-level files.
|
||||
- [ ] No duplicate docs with conflicting instructions.
|
||||
- [ ] No generated caches committed.
|
||||
- [ ] No secrets committed.
|
||||
- [ ] `.env.example` updated if env vars changed.
|
||||
|
||||
## 2. Backend
|
||||
|
||||
- [ ] App starts.
|
||||
- [ ] Health endpoint returns envelope or documented health format.
|
||||
- [ ] API routes grouped logically.
|
||||
- [ ] Validation errors are structured.
|
||||
- [ ] Database models match schema docs.
|
||||
- [ ] Geometry fields are not plain unvalidated strings.
|
||||
- [ ] Tests exist for implemented endpoints.
|
||||
|
||||
## 3. Frontend
|
||||
|
||||
- [ ] App starts.
|
||||
- [ ] No blank route screens.
|
||||
- [ ] API client centralizes envelope parsing.
|
||||
- [ ] Loading, empty, error states present.
|
||||
- [ ] Demo workflow visible.
|
||||
- [ ] Map shell does not depend on unavailable live data.
|
||||
|
||||
## 4. Geospatial Logic
|
||||
|
||||
- [ ] CRS metadata preserved.
|
||||
- [ ] Area calculations are server-side.
|
||||
- [ ] Invalid geometries rejected.
|
||||
- [ ] Demo fixtures load correctly.
|
||||
- [ ] No fake geospatial metrics presented as real.
|
||||
|
||||
## 5. Documentation
|
||||
|
||||
- [ ] Changelog updated.
|
||||
- [ ] Build status updated.
|
||||
- [ ] Execution log updated.
|
||||
- [ ] Known limitations updated if needed.
|
||||
|
||||
## 6. Commands
|
||||
|
||||
Run what is available:
|
||||
|
||||
```bash
|
||||
python -m pytest
|
||||
npm test
|
||||
npm run build
|
||||
npm run lint
|
||||
docker compose config
|
||||
```
|
||||
|
||||
If commands are not available yet, Codex must document why.
|
||||
@@ -0,0 +1,27 @@
|
||||
# M9 Long-Form Codex Prompt Variants
|
||||
|
||||
Use these prompts when Codex needs a more specific instruction after the master prompt.
|
||||
|
||||
## Prompt: Backend Foundation Only
|
||||
|
||||
Build only the backend foundation for GeoIntel. Do not work on frontend or AI. Implement FastAPI app startup, settings, health endpoint, response envelope, structured error handling, and basic tests. Follow `docs/API_CONTRACTS.md`, `docs/ERROR_HANDLING_AND_STATUSES.md`, and `docs/17-max-prep/M9_PASS_SCORECARDS.md`. Update execution log, build status and changelog.
|
||||
|
||||
## Prompt: Database Foundation Only
|
||||
|
||||
Implement database foundation only. Configure PostgreSQL/PostGIS using the documented Docker Compose environment. Add ORM models and migrations for projects, areas, datasets and analysis_runs. Geometry must use PostGIS-compatible fields. Do not implement AI or advanced datasets. Add tests where possible and update docs.
|
||||
|
||||
## Prompt: Dataset Manager Only
|
||||
|
||||
Implement the V1 Dataset Manager skeleton. Support upload metadata, storage path conventions, dataset status lifecycle and list/read endpoints. Use demo fixtures for tests. Do not fetch live GRB or Sentinel yet. Ensure source_mode is present. Update execution log and build status.
|
||||
|
||||
## Prompt: Frontend Shell Only
|
||||
|
||||
Implement the frontend shell with React TypeScript. Add routing, layout, project list, workspace shell, dataset manager shell and map workbench placeholder with correct states. Use API client envelope parsing. Do not hardcode fake analysis results.
|
||||
|
||||
## Prompt: QA/QC Skeleton Only
|
||||
|
||||
Implement pure geometry QA utilities and tests: IoU, precision, recall, F1 using fixture polygons. Add a backend service interface and endpoint skeleton if foundation exists. Do not require YOLO outputs yet; use fixture reference/predicted layers.
|
||||
|
||||
## Prompt: Stabilization Pass
|
||||
|
||||
Do not add features. Run all available tests/builds/lints. Fix failures. Update docs, changelog, known limitations and execution log. Remove dead code and root-folder clutter. Ensure app startup paths are documented.
|
||||
@@ -0,0 +1,83 @@
|
||||
# M9 Max Preparation Pack
|
||||
|
||||
Status: specification expansion after M8.
|
||||
Purpose: make GeoIntel as close as possible to a self-driving Codex project while still allowing Codex to make local implementation improvements.
|
||||
|
||||
## Goal
|
||||
|
||||
GeoIntel must be prepared so that Codex can:
|
||||
|
||||
1. read the repository,
|
||||
2. understand the product and constraints,
|
||||
3. build the foundation,
|
||||
4. validate itself,
|
||||
5. recover from common failures,
|
||||
6. report honestly what was completed,
|
||||
7. avoid architectural drift.
|
||||
|
||||
## Principle
|
||||
|
||||
Strict on architecture. Flexible on implementation details.
|
||||
|
||||
Codex may improve:
|
||||
|
||||
- component structure inside the approved route/component map,
|
||||
- service internals if IO contracts remain stable,
|
||||
- validation messages if API envelope remains stable,
|
||||
- tests if they increase coverage,
|
||||
- UI polish if it does not change the workflow.
|
||||
|
||||
Codex may not change without explicit approval:
|
||||
|
||||
- backend framework,
|
||||
- frontend framework,
|
||||
- database choice,
|
||||
- PostGIS requirement,
|
||||
- core entity names,
|
||||
- API response envelope,
|
||||
- dataset storage layout,
|
||||
- project positioning as a GeoAI Workbench,
|
||||
- V1 scope freeze.
|
||||
|
||||
## M9 Additions
|
||||
|
||||
This pack adds:
|
||||
|
||||
- final autonomous build doctrine,
|
||||
- exact day-one Codex master prompt,
|
||||
- build pass scorecards,
|
||||
- gap-to-task conversion rules,
|
||||
- real-versus-demo data policy,
|
||||
- geospatial edge case handling,
|
||||
- failure mode catalog,
|
||||
- module data contracts,
|
||||
- UI empty/loading/error states,
|
||||
- API validation examples,
|
||||
- seed fixtures policy,
|
||||
- regression map,
|
||||
- implementation review scripts,
|
||||
- handoff checklist.
|
||||
|
||||
## Expected Use Tomorrow
|
||||
|
||||
1. Extract the full zip.
|
||||
2. Open the repository in Codex.
|
||||
3. Paste `prompts/codex/M9_DAY_ONE_MASTER_PROMPT.md`.
|
||||
4. Let Codex run Pass 0 first.
|
||||
5. Require Codex to update `docs/CODEX_EXECUTION_LOG.md` after each pass.
|
||||
6. Do not allow feature expansion until Pass 1-4 are green.
|
||||
|
||||
## Success Definition
|
||||
|
||||
The preparation is successful if Codex can start from an empty implementation and produce:
|
||||
|
||||
- a working FastAPI app,
|
||||
- a working React app,
|
||||
- Docker Compose services,
|
||||
- PostGIS models/migrations,
|
||||
- project/area/dataset APIs,
|
||||
- demo fixture loading,
|
||||
- initial map UI shell,
|
||||
- validation and health checks,
|
||||
- tests for the implemented pieces,
|
||||
- a changelog and execution log.
|
||||
@@ -0,0 +1,133 @@
|
||||
# M9 Module Dataflow Checklist
|
||||
|
||||
Every module must declare its dataflow.
|
||||
|
||||
## Dataset Manager
|
||||
|
||||
Input:
|
||||
|
||||
- file upload,
|
||||
- project id,
|
||||
- optional area id.
|
||||
|
||||
Processing:
|
||||
|
||||
- validate extension,
|
||||
- store raw file,
|
||||
- inspect metadata,
|
||||
- persist dataset record,
|
||||
- schedule optional processing job.
|
||||
|
||||
Output:
|
||||
|
||||
- dataset record,
|
||||
- status,
|
||||
- metadata.
|
||||
|
||||
## Raster Lab
|
||||
|
||||
Input:
|
||||
|
||||
- raster dataset id,
|
||||
- optional area geometry.
|
||||
|
||||
Processing:
|
||||
|
||||
- read raster metadata,
|
||||
- compute bounds,
|
||||
- inspect bands,
|
||||
- clip if requested,
|
||||
- generate preview/tiles later.
|
||||
|
||||
Output:
|
||||
|
||||
- metadata,
|
||||
- preview descriptor,
|
||||
- derived dataset if clipped.
|
||||
|
||||
## Vector Lab
|
||||
|
||||
Input:
|
||||
|
||||
- vector dataset id,
|
||||
- optional area geometry.
|
||||
|
||||
Processing:
|
||||
|
||||
- load features,
|
||||
- validate CRS,
|
||||
- compute feature count,
|
||||
- compute bounds,
|
||||
- clip if requested.
|
||||
|
||||
Output:
|
||||
|
||||
- vector metadata,
|
||||
- clipped layer,
|
||||
- operation report.
|
||||
|
||||
## Detection Lab
|
||||
|
||||
Input:
|
||||
|
||||
- raster dataset id,
|
||||
- model id,
|
||||
- threshold,
|
||||
- classes.
|
||||
|
||||
Processing:
|
||||
|
||||
- tile raster,
|
||||
- run model adapter,
|
||||
- merge detections,
|
||||
- georeference outputs,
|
||||
- persist detection layer.
|
||||
|
||||
Output:
|
||||
|
||||
- detection dataset/layer,
|
||||
- analysis run,
|
||||
- metrics.
|
||||
|
||||
## Segmentation Lab
|
||||
|
||||
Input:
|
||||
|
||||
- raster dataset id,
|
||||
- model id,
|
||||
- classes/prompts.
|
||||
|
||||
Processing:
|
||||
|
||||
- generate masks,
|
||||
- polygonize,
|
||||
- clean geometry,
|
||||
- compute areas,
|
||||
- persist layer.
|
||||
|
||||
Output:
|
||||
|
||||
- mask path,
|
||||
- polygon layer,
|
||||
- metrics.
|
||||
|
||||
## QA/QC Lab
|
||||
|
||||
Input:
|
||||
|
||||
- reference vector layer,
|
||||
- predicted vector layer,
|
||||
- matching threshold.
|
||||
|
||||
Processing:
|
||||
|
||||
- spatial match,
|
||||
- IoU calculation,
|
||||
- precision/recall/F1,
|
||||
- false positive/negative features.
|
||||
|
||||
Output:
|
||||
|
||||
- QA metrics,
|
||||
- findings,
|
||||
- QA overlay layers.
|
||||
@@ -0,0 +1,91 @@
|
||||
# M9 Build Pass Scorecards
|
||||
|
||||
Use these scorecards after every Codex pass. A pass is not considered complete until its scorecard is mostly green.
|
||||
|
||||
## Pass 0 — Audit
|
||||
|
||||
- [ ] Repository tree inspected.
|
||||
- [ ] Existing docs summarized.
|
||||
- [ ] Missing implementation listed.
|
||||
- [ ] Build blockers listed.
|
||||
- [ ] Next pass selected.
|
||||
- [ ] No feature code added.
|
||||
|
||||
## Pass 1 — Backend Foundation
|
||||
|
||||
- [ ] FastAPI app starts.
|
||||
- [ ] Health endpoint exists.
|
||||
- [ ] Settings load from environment.
|
||||
- [ ] CORS configured for local frontend.
|
||||
- [ ] API envelope helper exists.
|
||||
- [ ] Error handler exists.
|
||||
- [ ] Backend tests run.
|
||||
|
||||
## Pass 2 — Database Foundation
|
||||
|
||||
- [ ] SQLAlchemy or approved ORM configured.
|
||||
- [ ] Alembic migrations initialized.
|
||||
- [ ] PostGIS extension migration exists.
|
||||
- [ ] Project model exists.
|
||||
- [ ] Area model exists with geometry.
|
||||
- [ ] Dataset model exists.
|
||||
- [ ] Local database connection documented.
|
||||
|
||||
## Pass 3 — Project/Area APIs
|
||||
|
||||
- [ ] Create/list/read project.
|
||||
- [ ] Create/list/read area.
|
||||
- [ ] GeoJSON polygon validation.
|
||||
- [ ] Area size calculation.
|
||||
- [ ] Envelope responses.
|
||||
- [ ] Error responses for invalid geometry.
|
||||
- [ ] Tests for happy and failure paths.
|
||||
|
||||
## Pass 4 — Dataset Manager Skeleton
|
||||
|
||||
- [ ] Dataset upload endpoint.
|
||||
- [ ] File stored under documented storage root.
|
||||
- [ ] Metadata extraction placeholder with real file inspection when possible.
|
||||
- [ ] Dataset list/read APIs.
|
||||
- [ ] Status lifecycle present.
|
||||
- [ ] Tests with fixtures.
|
||||
|
||||
## Pass 5 — Frontend Foundation
|
||||
|
||||
- [ ] React app starts.
|
||||
- [ ] Route shell exists.
|
||||
- [ ] API client uses envelope.
|
||||
- [ ] Error/loading/empty states exist.
|
||||
- [ ] Project list page exists.
|
||||
- [ ] Workspace shell exists.
|
||||
|
||||
## Pass 6 — Map Workbench Shell
|
||||
|
||||
- [ ] MapLibre or approved map abstraction installed.
|
||||
- [ ] Area polygon can be displayed.
|
||||
- [ ] Demo GeoJSON can be loaded.
|
||||
- [ ] Layer panel shell exists.
|
||||
- [ ] No hardcoded fake analysis results.
|
||||
|
||||
## Pass 7 — Raster/Vector Core Skeleton
|
||||
|
||||
- [ ] Raster metadata endpoint skeleton.
|
||||
- [ ] Vector metadata endpoint skeleton.
|
||||
- [ ] CRS field exposed.
|
||||
- [ ] Bounds field exposed.
|
||||
- [ ] UI metadata panels exist.
|
||||
|
||||
## Pass 8 — QA/QC Skeleton
|
||||
|
||||
- [ ] QA service interface exists.
|
||||
- [ ] IoU function unit-tested with fixtures.
|
||||
- [ ] Precision/recall formulas implemented.
|
||||
- [ ] QA endpoint accepts reference and predicted layer IDs or fixture IDs.
|
||||
- [ ] QA result card exists.
|
||||
|
||||
## Pass 9 — Stabilization
|
||||
|
||||
- [ ] All smoke commands documented.
|
||||
- [ ] Changelog updated.
|
||||
- [ ] Known limitations updated.
|
||||
- [ ] Next advanced module recommendation written.
|
||||
@@ -0,0 +1,59 @@
|
||||
# Real vs Demo Data Policy
|
||||
|
||||
GeoIntel may use demo fixtures during early development, but the UI and backend must clearly distinguish demo data from live data.
|
||||
|
||||
## Data Categories
|
||||
|
||||
### Real Data
|
||||
|
||||
Data fetched from or uploaded by a real source:
|
||||
|
||||
- GRB WFS/cache,
|
||||
- user-uploaded GeoTIFF,
|
||||
- user-uploaded GeoJSON/Shapefile/GPKG,
|
||||
- Sentinel scene,
|
||||
- DHMV product.
|
||||
|
||||
### Demo Fixture Data
|
||||
|
||||
Small repository-contained examples used for development and tests:
|
||||
|
||||
- `demo/geel/reference_buildings.geojson`,
|
||||
- `demo/geel/demo_detections.geojson`,
|
||||
- `fixtures/geojson/*`.
|
||||
|
||||
### Synthetic Test Data
|
||||
|
||||
Minimal generated data used only in unit tests.
|
||||
|
||||
## Rules
|
||||
|
||||
- Demo data may be used to build UI states and verify pipelines.
|
||||
- Demo data must be labeled as demo in API responses.
|
||||
- Real-data adapters must not silently fall back to demo data.
|
||||
- A failed external fetch must return an error/status, not demo data.
|
||||
- Synthetic data must not appear in production UI unless under a test/demo route.
|
||||
|
||||
## Dataset Metadata Field
|
||||
|
||||
Every dataset must include:
|
||||
|
||||
```json
|
||||
{
|
||||
"source_mode": "real|demo|synthetic",
|
||||
"source_name": "GRB|OSM|user_upload|fixture|generated_test",
|
||||
"license": "string or unknown",
|
||||
"retrieved_at": "ISO date or null"
|
||||
}
|
||||
```
|
||||
|
||||
## UI Requirement
|
||||
|
||||
The dataset table must display a source badge:
|
||||
|
||||
- Real
|
||||
- Demo
|
||||
- Synthetic
|
||||
- Unknown
|
||||
|
||||
Synthetic should never be shown in normal user workflows.
|
||||
@@ -0,0 +1,81 @@
|
||||
# M9 Regression Map
|
||||
|
||||
These are the most likely regressions during autonomous builds.
|
||||
|
||||
## API Envelope Drift
|
||||
|
||||
Risk: some endpoints return raw data while others return envelopes.
|
||||
|
||||
Prevention:
|
||||
|
||||
- central response helper,
|
||||
- API client tests,
|
||||
- sample responses.
|
||||
|
||||
## Geometry Stored Incorrectly
|
||||
|
||||
Risk: GeoJSON stored as text everywhere.
|
||||
|
||||
Prevention:
|
||||
|
||||
- PostGIS geometry columns,
|
||||
- schema tests,
|
||||
- validation utilities.
|
||||
|
||||
## Demo Data Masquerades as Real Data
|
||||
|
||||
Risk: UI shows fixture metrics without labeling them.
|
||||
|
||||
Prevention:
|
||||
|
||||
- source_mode field,
|
||||
- demo badge,
|
||||
- no fallback-to-fixture for external failures.
|
||||
|
||||
## Frontend State Duplication
|
||||
|
||||
Risk: every component fetches differently.
|
||||
|
||||
Prevention:
|
||||
|
||||
- central API client,
|
||||
- shared hooks,
|
||||
- state contracts.
|
||||
|
||||
## Heavy AI Implemented Too Early
|
||||
|
||||
Risk: Codex spends time on YOLO/SAM before storage and datasets work.
|
||||
|
||||
Prevention:
|
||||
|
||||
- pass scorecards,
|
||||
- V1 ordering,
|
||||
- disabled state for model features.
|
||||
|
||||
## CRS Ignored
|
||||
|
||||
Risk: area/length values wrong.
|
||||
|
||||
Prevention:
|
||||
|
||||
- CRS field mandatory,
|
||||
- projected calculations documented,
|
||||
- geospatial edge cases.
|
||||
|
||||
## Docs Not Updated
|
||||
|
||||
Risk: implementation diverges from specs.
|
||||
|
||||
Prevention:
|
||||
|
||||
- Definition of Done includes docs,
|
||||
- execution log mandatory.
|
||||
|
||||
## Root Folder Pollution
|
||||
|
||||
Risk: scripts and generated outputs appear at root.
|
||||
|
||||
Prevention:
|
||||
|
||||
- repository conventions,
|
||||
- review script.
|
||||
@@ -0,0 +1,108 @@
|
||||
# M9 UI State Specification
|
||||
|
||||
Every page and major component must implement these states.
|
||||
|
||||
## Required States
|
||||
|
||||
### Initial
|
||||
|
||||
No user action yet.
|
||||
|
||||
Example copy:
|
||||
|
||||
> Start by creating a project or opening the Geel demo.
|
||||
|
||||
### Loading
|
||||
|
||||
Data is being fetched or processed.
|
||||
|
||||
Requirements:
|
||||
|
||||
- spinner or skeleton,
|
||||
- clear label,
|
||||
- no layout jump where avoidable.
|
||||
|
||||
### Empty
|
||||
|
||||
Request succeeded but no records exist.
|
||||
|
||||
Example:
|
||||
|
||||
> No datasets have been added to this project yet.
|
||||
|
||||
### Ready
|
||||
|
||||
Data exists and actions are available.
|
||||
|
||||
### Error
|
||||
|
||||
Request failed or validation failed.
|
||||
|
||||
Requirements:
|
||||
|
||||
- readable error,
|
||||
- retry action where safe,
|
||||
- technical details hidden behind details/expand if useful.
|
||||
|
||||
### Disabled/Future
|
||||
|
||||
Feature is planned but not implemented in V1.
|
||||
|
||||
Requirements:
|
||||
|
||||
- show disabled state,
|
||||
- explain why,
|
||||
- do not show fake results.
|
||||
|
||||
## Page Requirements
|
||||
|
||||
### Home
|
||||
|
||||
- Initial: explain GeoIntel.
|
||||
- Empty: no recent projects.
|
||||
- Ready: project cards and demo card.
|
||||
|
||||
### Project Workspace
|
||||
|
||||
- Loading project.
|
||||
- Missing project error.
|
||||
- Empty datasets/areas states.
|
||||
- Ready dashboard.
|
||||
|
||||
### Dataset Manager
|
||||
|
||||
- Empty upload area.
|
||||
- Upload progress.
|
||||
- Upload failed.
|
||||
- Processing.
|
||||
- Ready metadata.
|
||||
|
||||
### Map Workbench
|
||||
|
||||
- No area selected.
|
||||
- Area loaded.
|
||||
- Layer loading.
|
||||
- Layer error.
|
||||
- Unsupported layer type.
|
||||
|
||||
### Detection Lab
|
||||
|
||||
- No raster selected.
|
||||
- No model configured.
|
||||
- Running job.
|
||||
- Completed detections.
|
||||
- Failed inference.
|
||||
|
||||
### QA/QC Lab
|
||||
|
||||
- Missing reference dataset.
|
||||
- Missing predicted dataset.
|
||||
- Running comparison.
|
||||
- Metrics ready.
|
||||
- No matches found.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not leave blank panels.
|
||||
- Do not show random demo metrics in ready state.
|
||||
- Do not hide errors in console only.
|
||||
Reference in New Issue
Block a user