GeoIntel Kempen is a GeoAI Workbench for the Belgian Kempen. It is designed as a portfolio-grade project combining GIS, remote sensing, raster/vector processing, computer vision, QA/QC and geospatial exports.

GeoIntel is not a generic dashboard or chatbot. The core product is:

data → processing → geospatial output → QA/QC → export

Current milestone

M14 — Build Launch Package

The canonical start point is now:

CODEX_START.md
docs/00-start/START_HERE.md
docs/40-build-launch/SPRINT_1_SCOPE_FREEZE.md
docs/40-build-launch/BUILD_SUCCESS_DEFINITION.md
docs/40-build-launch/BUILD_ORDER_GRAPH.md

Older M0-M13 handoff files are retained as historical preparation artifacts. The M14 build launch docs, M13 optimization docs, M12 final run-readiness docs, M11 governance docs and canonical specs take precedence.

Core V1 vertical slice

The first implementation target is:

Project + Area creation.
Dataset registration/upload and metadata extraction.
Reference building layer loading.
Predicted detection layer loading/import.
QA/QC matching against reference polygons.
Metrics and false positive/false negative outputs.
GeoJSON export.
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:

docs/00-start/START_HERE.md
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

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:

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:

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:

python -m pip install -e backend/.[dev]
cd frontend && npm install

Run full readiness checks (with no scope expansion):

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 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:

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):

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:

make m13

The full readiness path remains:

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:

make m14

Full readiness remains:

make readiness

Sprint 1 execution (Sprint 1 only)

From a clean machine:

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:

docker compose ps

Verify the browser-facing API proxy after rebuilding Docker images:

bash scripts/verify_browser_runtime.sh http://localhost:1202 http://localhost:8000/health

Verify the Docker GIS runtime after rebuilding the backend image:

bash scripts/verify_gis_runtime.sh http://localhost:1202

On the LAN host use the published browser URL, for example:

bash scripts/verify_gis_runtime.sh http://192.168.10.150:1202

Load the explicit offline demo workflow:

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:

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 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