# GeoIntel Kempen

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:

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