293 lines
8.6 KiB
Markdown
293 lines
8.6 KiB
Markdown
# GeoIntel Belgium and the Belgian North Sea
|
|
|
|
GeoIntel is a map-first GeoAI Workbench for Belgium and the Belgian North Sea.
|
|
It combines governed official-source coverage, raster/vector processing,
|
|
historical comparison, computer vision, QA/QC and geospatial exports.
|
|
|
|
Mol and the Kempen remain deep regression and model-validation references. The
|
|
release scope is all of Belgium plus legally labelled Belgian maritime zones;
|
|
source coverage remains explicit per theme and jurisdiction.
|
|
|
|
GeoIntel is not a generic dashboard or chatbot. The core product is:
|
|
|
|
> data → processing → geospatial output → QA/QC → export
|
|
|
|
## Current milestone
|
|
|
|
**v1.0.0 - Belgium/North Sea release**
|
|
|
|
The canonical release controls are:
|
|
|
|
- `docs/00-start/START_HERE.md`
|
|
- `docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md`
|
|
- `docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md`
|
|
- `docs/RELEASE_RUNBOOK.md`
|
|
- `docs/KNOWN_LIMITATIONS.md`
|
|
- `docs/DEFINITION_OF_DONE.md`
|
|
|
|
Older milestone and sprint handoff files remain historical evidence. They do
|
|
not override the active national/maritime scope freeze or RC roadmap.
|
|
|
|
## Core V1 vertical slice
|
|
|
|
The first implementation target is:
|
|
|
|
1. Project + Area creation.
|
|
2. Dataset registration/upload and metadata extraction.
|
|
3. Reference building layer loading.
|
|
4. Predicted detection layer loading/import.
|
|
5. QA/QC matching against reference polygons.
|
|
6. Metrics and false positive/false negative outputs.
|
|
7. GeoJSON export.
|
|
8. Minimal map/workbench UI.
|
|
|
|
## Primary stack
|
|
|
|
- Frontend: React, TypeScript, MapLibre GL, Deck.gl, Tailwind.
|
|
- Backend: FastAPI, Python.
|
|
- Database: PostgreSQL + PostGIS.
|
|
- GIS processing: GeoPandas, Shapely, Rasterio, PyProj, GDAL.
|
|
- AI: PyTorch, Ultralytics YOLO, SAM-compatible architecture.
|
|
- Jobs: Redis + RQ.
|
|
- Storage: local filesystem first, MinIO-compatible later.
|
|
|
|
## Codex instructions
|
|
|
|
Codex must start with:
|
|
|
|
1. `docs/00-start/START_HERE.md`
|
|
2. `prompts/codex/M11_ARCHITECT_MASTER_PROMPT.md`
|
|
|
|
Then follow the build order in:
|
|
|
|
- `docs/build/BUILD_ORDER_DEPENDENCY_GRAPH.md`
|
|
- `docs/build/CODEX_OPERATING_SYSTEM.md`
|
|
|
|
Before every implementation pass, run available preflight/smoke scripts where applicable.
|
|
|
|
## Repo principle
|
|
|
|
This is a documentation-driven engineering repo. The documentation is not decorative; it is the control system for autonomous implementation.
|
|
|
|
## Fastest Day 1 command path
|
|
|
|
```bash
|
|
make readiness
|
|
```
|
|
|
|
## Unraid / Tower deployment
|
|
|
|
GeoIntel runs on Unraid as an all-in-one DockerMan-native container. The container embeds PostGIS, runs the FastAPI backend internally, and serves the frontend through nginx on one editable web port.
|
|
|
|
Unraid template assets live in:
|
|
|
|
- `deploy/unraid/geointel.env.example`
|
|
- `deploy/unraid/geointel-unraid-template.xml`
|
|
- `deploy/unraid/geointel-icon.svg`
|
|
- `deploy/unraid/geointel-icon.png`
|
|
- `docker-compose.unraid.yml`
|
|
|
|
Copy the Unraid env template to `.env` in the checkout and edit ports/paths there:
|
|
|
|
```bash
|
|
cd /mnt/user/appdata/geointel
|
|
cp deploy/unraid/geointel.env.example .env
|
|
nano .env
|
|
docker build -f deploy/unraid/Dockerfile.all-in-one -t geointel-all-in-one:latest .
|
|
bash deploy/unraid/run-dockerman-container.sh
|
|
```
|
|
|
|
Common editable values:
|
|
|
|
```env
|
|
GEOINTEL_FRONTEND_PORT=1202
|
|
GEOINTEL_STORAGE_PATH=/mnt/user/appdata/geointel/storage
|
|
GEOINTEL_POSTGIS_DATA_PATH=/mnt/user/appdata/geointel/postgres-data
|
|
```
|
|
|
|
The backend and PostGIS ports are intentionally not exposed to the LAN in the all-in-one runtime. See `deploy/unraid/README.md` for full setup, port-change and cleanup notes.
|
|
|
|
On Tower/Unraid, `scripts/deploy_tower.ps1` and `scripts/deploy_tower.sh` validate the Compose reference but build with plain `docker build`, then automatically install the editable DockerMan template as `/boot/config/plugins/dockerMan/templates-user/my-geointel.xml`, install the PNG icon as `/boot/config/plugins/dockerMan/images/geointel-icon.png`, remove any old Compose-owned `geointel` container and start the final container with DockerMan labels.
|
|
|
|
## Sprint 2 quick start
|
|
|
|
- Update dependencies:
|
|
|
|
```bash
|
|
python -m pip install -e backend/.[dev]
|
|
cd frontend && npm install
|
|
```
|
|
|
|
- Run full readiness checks (with no scope expansion):
|
|
|
|
```bash
|
|
python -m compileall backend/app
|
|
cd backend && python -m pytest
|
|
cd ../frontend && npm run typecheck && npm run build
|
|
bash scripts/run_readiness_check.sh
|
|
```
|
|
|
|
- Raster workflow validation command (backend only):
|
|
|
|
```bash
|
|
bash scripts/smoke_backend_import.sh
|
|
cd backend && python -c "from app.main import app; print(app.title)"
|
|
```
|
|
|
|
If `rasterio` is not installed, raster metadata endpoints return `RASTER_PROCESSING_UNAVAILABLE` and the frontend displays the
|
|
state as failed until the dependency is added.
|
|
|
|
## Sprint 4 raster foundation
|
|
|
|
- Raster operations now support:
|
|
- raster metadata extraction,
|
|
- raster preview generation,
|
|
- raster clip by area (with provenance on derived datasets),
|
|
- raster tile generation with manifest output.
|
|
- Raster services are dependency-aware:
|
|
- if `rasterio` is unavailable, endpoints return `RASTER_PROCESSING_UNAVAILABLE`.
|
|
- if preview dependencies (`numpy`, `pillow`) are unavailable, preview generation is unavailable with a clear error.
|
|
- Enable raster stack explicitly when needed:
|
|
|
|
```bash
|
|
cd backend && python -m pip install -e .[dev,raster]
|
|
```
|
|
|
|
## Sprint 5 raster analytics hardening
|
|
|
|
- Added raster band statistics (min/max/mean/std, nodata ratio/count, valid pixel count, dtype, optional histograms).
|
|
- Added raster reproject workflow with CRS validation and provenance persistence.
|
|
- Extended tile manifest expectations (`tile_set_id`, `tile_size`, `overlap`, `bounds`, `source_raster_id`, `tile_paths`, `tile_server`).
|
|
- Clarified raster operation availability in frontend/backend docs (`RASTER_PROCESSING_UNAVAILABLE` and invalid-CRS cases).
|
|
|
|
- Raster workflow command set (where available):
|
|
|
|
```bash
|
|
cd backend
|
|
python -m pip install -e .[dev,raster]
|
|
python -m pytest
|
|
cd ../frontend
|
|
npm run typecheck
|
|
npm run build
|
|
```
|
|
|
|
Then give Codex the prompt in:
|
|
|
|
- `prompts/codex/final/DAY_1_MASTER_PROMPT.md`
|
|
|
|
|
|
## M13 Codex optimization
|
|
|
|
For the first serious Codex build run, use:
|
|
|
|
- `prompts/codex/m13/DAY_1_OPTIMIZED_MASTER_PROMPT.md`
|
|
|
|
Codex should also use the relevant reusable skill under `skills/` for each implementation pass. Validate the optimization assets with:
|
|
|
|
```bash
|
|
make m13
|
|
```
|
|
|
|
The full readiness path remains:
|
|
|
|
```bash
|
|
make readiness
|
|
```
|
|
|
|
|
|
## M14 Build Launch
|
|
|
|
For the first serious implementation run, use:
|
|
|
|
- `docs/40-build-launch/SPRINT_1_SCOPE_FREEZE.md`
|
|
- `docs/40-build-launch/BUILD_SUCCESS_DEFINITION.md`
|
|
- `docs/40-build-launch/CODEX_STOP_RULES.md`
|
|
- `prompts/codex/m14/CODEX_FIRST_DAY_MASTER_PROMPT.md`
|
|
|
|
Validate launch assets with:
|
|
|
|
```bash
|
|
make m14
|
|
```
|
|
|
|
Full readiness remains:
|
|
|
|
```bash
|
|
make readiness
|
|
```
|
|
|
|
## Sprint 1 execution (Sprint 1 only)
|
|
|
|
From a clean machine:
|
|
|
|
```bash
|
|
cd backend && python -m pip install -e .[dev]
|
|
cd ..
|
|
make backend-install
|
|
make frontend-install
|
|
make readiness
|
|
```
|
|
|
|
Copy `.env.example` to `.env` only when you want local overrides. Docker Compose has safe defaults for the local PostGIS/backend/frontend stack and does not require a root `.env` file to exist.
|
|
|
|
With Docker Compose, open the workbench at `http://localhost:1202`.
|
|
|
|
The Docker frontend is served by nginx and proxies `/api` and `/health` to the backend container, so browser clients should use the frontend URL only, for example `http://192.168.10.150:1202` on a LAN host.
|
|
|
|
Runtime containers include healthchecks for PostGIS, backend and frontend. After
|
|
startup, inspect them with:
|
|
|
|
```bash
|
|
docker compose ps
|
|
```
|
|
|
|
Verify the browser-facing API proxy after rebuilding Docker images:
|
|
|
|
```bash
|
|
bash scripts/verify_browser_runtime.sh http://localhost:1202 http://localhost:8000/health
|
|
```
|
|
|
|
Verify the Docker GIS runtime after rebuilding the backend image:
|
|
|
|
```bash
|
|
bash scripts/verify_gis_runtime.sh http://localhost:1202
|
|
```
|
|
|
|
On the LAN host use the published browser URL, for example:
|
|
|
|
```bash
|
|
bash scripts/verify_gis_runtime.sh http://192.168.10.150:1202
|
|
```
|
|
|
|
Load the explicit offline demo workflow:
|
|
|
|
```bash
|
|
curl -X POST http://192.168.10.150:1202/api/v1/demo/workflow
|
|
```
|
|
|
|
If `/api/v1/projects` returns frontend HTML instead of a JSON envelope, rebuild
|
|
and restart the frontend container.
|
|
|
|
Useful direct verification commands:
|
|
|
|
```bash
|
|
python -m compileall backend/app
|
|
cd backend && python -c "from app.main import app; print(app.title)"
|
|
python -m pytest
|
|
cd ../frontend && npm run typecheck
|
|
cd ../frontend && npm run build
|
|
docker compose config
|
|
bash scripts/run_readiness_check.sh
|
|
```
|
|
|
|
If `make` or `docker` are unavailable in your shell, run the equivalent script entrypoints directly:
|
|
|
|
```bash
|
|
bash scripts/backend_install.sh
|
|
bash scripts/backend_test.sh
|
|
bash scripts/frontend_install.sh
|
|
bash scripts/frontend_typecheck.sh
|
|
bash scripts/frontend_build.sh
|
|
bash scripts/run_readiness_check.sh
|
|
```
|