geointel/docs/ARCHITECTURE.md

Architecture

1. Overzicht

GeoIntel bestaat uit:

• React/TypeScript frontend
• FastAPI backend
• PostgreSQL/PostGIS database
• background job queue
• file/object storage
• GIS processing services
• AI inference services

2. Hoofdcomponenten

Frontend
  ↓ REST/WebSocket
FastAPI Backend
  ↓
PostgreSQL + PostGIS
  ↓
Storage: uploads, processed rasters, tiles, masks, exports
  ↓
Workers: GIS processing, AI inference, QA/QC, export

3. Frontend

Aanbevolen stack:

• React
• TypeScript
• MapLibre GL
• Deck.gl
• Tailwind
• TanStack Query
• Zustand of vergelijkbare lichte state store
• Recharts voor eenvoudige grafieken

Belangrijke principes:

• kaart centraal, maar analysepanelen even belangrijk
• labs per workflow
• duidelijke jobstatus
• outputs altijd exporteerbaar
• geen verborgen mockgedrag

4. Backend

Aanbevolen stack:

• FastAPI
• SQLAlchemy 2.x
• GeoAlchemy2
• Alembic
• Pydantic
• RQ/Celery
• Rasterio
• GeoPandas
• Shapely
• PyProj
• NumPy
• OpenCV
• Ultralytics/PyTorch

5. Database

PostgreSQL met PostGIS is verplicht voor:

• projectgebieden
• vectorfeatures
• detectiepolygonen
• segmentatiepolygonen
• spatial joins
• intersects
• IoU berekeningen
• bounds queries

6. Storage

Bewaar grote bestanden niet in de database.

Opslagcategorieën:

• originele uploads
• verwerkte rasters
• raster tiles
• masks
• model outputs
• exports
• rapporten

Database bewaart metadata en paden.

7. Jobs

Langlopende processen moeten via background jobs:

• raster metadata extraction
• raster clipping
• raster tiling
• vector import
• AI inference
• segmentation polygonize
• QA/QC
• change detection
• export generation

8. AI Inference

Inference pipeline:

Raster dataset
→ clip to area
→ tile raster
→ normalize/preprocess
→ model inference
→ convert pixel coords to geospatial coords
→ merge/filter outputs
→ save detections/segmentations
→ expose as map layer

9. CRS-regels

• Alle interne geometrieën worden opgeslagen in PostGIS met bekende SRID.
• Voor metrische berekeningen wordt een geschikte projectie gebruikt.
• API-output naar frontend mag in EPSG:4326 of WebMercator-compatible formaat.
• Elke dataset zonder CRS krijgt status needs_crs_review.

10. Developmentstrategie

Bouwvolgorde:

1. backend foundation
2. database schema
3. project/area API
4. dataset upload en metadata
5. frontend workspace en kaart
6. vector import
7. raster import
8. processing jobs
9. detection lab
10. QA/QC
11. export