# Environment Specification

## Required runtime services

- Backend: FastAPI.
- Frontend: Vite React.
- Database: PostgreSQL with PostGIS.
- Optional queue: Redis/RQ after core APIs work.

## Environment variables

### Backend

```env
GEOINTEL_ENV=development
GEOINTEL_API_PREFIX=/api/v1
DATABASE_URL=postgresql+psycopg://geointel:geointel@db:5432/geointel
STORAGE_ROOT=/app/storage
MAX_UPLOAD_MB=500
YOLO_ENABLED=false
YOLO_MODEL_PATH=
YOLO_MODEL_VERSION=
YOLO_MAX_TILES=100
YOLO_MAX_DETECTIONS=1000
YOLO_DUPLICATE_IOU_THRESHOLD=0.5
ENABLE_GRB_WFS=false
GRB_WFS_URL=

# Explicit read-only source-edition probes (no provider import).
SOURCE_CATALOG_PROBE_ENABLED=true
SOURCE_CATALOG_GRB_WFS_URL=https://geo.api.vlaanderen.be/GRB/wfs
SOURCE_CATALOG_STATBEL_DCAT_URL=https://doc.statbel.be/publications/DCAT/DCAT_opendata_datasets.ttl
SOURCE_CATALOG_STATBEL_MAX_RESPONSE_MB=5
SOURCE_CATALOG_ALZ_RELEASE_URL=https://landbouwcijfers.vlaanderen.be/open-geodata-landbouwgebruikspercelen
SOURCE_CATALOG_PROBE_TIMEOUT_SECONDS=10
SOURCE_CATALOG_PROBE_MAX_RESPONSE_MB=2
SOURCE_CATALOG_PROBE_CACHE_TTL_SECONDS=900
OSM_OVERPASS_URL=https://overpass-api.de/api/interpreter
```

The Statbel limit is separate because the official Turtle catalog is larger
than the bounded OGC/HTML metadata responses. The probe parses only release
metadata and validates distribution identities; it never follows population
ZIP or XLSX links.

### Frontend

```env
VITE_API_BASE_URL=
VITE_API_PROXY_TARGET=http://localhost:8000
VITE_MAP_STYLE_URL=
```

`VITE_API_BASE_URL` is intentionally empty by default so the browser calls the
same origin as the frontend. In Docker Compose, nginx serves the built frontend
and reverse proxies `/api` and `/health` to the backend container. For local
Vite development, `VITE_API_PROXY_TARGET` can point to the local backend.

If `VITE_MAP_STYLE_URL` is empty, the frontend uses the built-in OpenStreetMap
road raster basemap with visible attribution. This is suitable for local V1
testing and demos. For production, commercial use or heavier traffic, set
`VITE_MAP_STYLE_URL` to a managed MapLibre style URL from an appropriate tile
provider instead of relying on the public OpenStreetMap tile service.

## Docker compose services

- `db`: PostGIS image.
- `backend`: FastAPI app.
- `frontend`: nginx-served Vite build with `/api` and `/health` reverse proxy.
- `redis`: optional, introduced when async jobs are implemented.

## Docker GIS capabilities

The default backend Docker image installs the approved GIS runtime extra and
system libraries needed for existing raster/vector processing:

- rasterio
- numpy
- pillow
- geopandas
- pyogrio
- GDAL/GEOS/PROJ runtime packages

After a Docker rebuild, the browser-facing runtime should report:

```json
{
  "postgis": true,
  "rasterio": true,
  "geopandas": true
}
```

Verify this through the frontend proxy:

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

For a LAN deployment, replace the URL with the published host address, for
example `http://192.168.10.150:1202`.

## Local development commands

Backend:

```bash
cd backend
uvicorn app.main:app --reload
pytest
```

Frontend:

```bash
cd frontend
npm install
npm run dev
npm run build
```

## Storage mounts

Development storage:

```text
storage/originals
storage/derived
storage/tiles
storage/masks
storage/exports
storage/models
```