Initial GeoIntel V1 foundation

2026-06-16 23:36:32 +02:00
commit 6ea3586a3e
605 changed files with 45284 additions and 0 deletions
@@ -0,0 +1,110 @@
+# 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
+ENABLE_GRB_WFS=false
+GRB_WFS_URL=
+OSM_OVERPASS_URL=https://overpass-api.de/api/interpreter
+```
+
+### Frontend
+
+```env
+VITE_API_BASE_URL=
+VITE_API_PROXY_TARGET=http://localhost:8000
+VITE_MAP_STYLE_URL=https://demotiles.maplibre.org/style.json
+```
+
+`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.
+
+## 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
+```