Initial public release

docs/ARCHITECTURE.md

@@ -0,0 +1,148 @@
+# 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
+
+```text
+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:
+
+```text
+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