Initial public release

adr/ADR-001-technology-stack.md

@@ -0,0 +1,25 @@
+# ADR-001 — Technology Stack
+
+## Status
+Accepted for V1.
+
+## Context
+GeoIntel Kempen must demonstrate modern web development, geospatial processing, and GeoAI engineering. The stack must be realistic for a portfolio project while remaining close to professional workflows.
+
+## Decision
+Use:
+
+- Frontend: React + TypeScript.
+- Map UI: MapLibre GL with Deck.gl where advanced overlays are useful.
+- Backend: FastAPI.
+- Database: PostgreSQL + PostGIS.
+- Processing: GeoPandas, Shapely, Rasterio, PyProj, GDAL-compatible tools.
+- AI: PyTorch with Ultralytics YOLO first; SAM/segmentation later.
+- Jobs: Redis + RQ for V1.
+- Storage: local filesystem with explicit storage abstraction.
+
+## Consequences
+This stack keeps the first build achievable while matching the vacancy profile closely: Python, raster/vector processing, computer vision, AI pipelines, and GIS outputs.
+
+## Non-goals
+Do not introduce Django, Flask, MongoDB, Firebase, or a second frontend framework unless a future ADR explicitly replaces this decision.

adr/ADR-002-postgis-choice.md

@@ -0,0 +1,27 @@
+# ADR-002 — PostGIS as Spatial Source of Truth
+
+## Status
+Accepted for V1.
+
+## Context
+GeoIntel stores areas, datasets, AI detections, segmentations, QA geometries, and exports. Spatial operations need to be queryable and persistent.
+
+## Decision
+Use PostgreSQL with PostGIS as the canonical database for:
+
+- project areas,
+- dataset spatial bounds,
+- vector features,
+- detection polygons/boxes,
+- segmentation polygons,
+- QA/QC geometries,
+- spatial metadata,
+- analysis outputs.
+
+Raw rasters, tiles, masks, and large binary artifacts stay on disk/object storage. PostGIS stores metadata and vectorized results.
+
+## Consequences
+The backend can do spatial filtering, intersections, bounding-box queries, and QA matching without reloading every file. The portfolio visibly demonstrates professional GIS database skills.
+
+## Non-goals
+Do not store full large rasters as database blobs in V1.

adr/ADR-003-grb-strategy.md

@@ -0,0 +1,23 @@
+# ADR-003 — GRB as Authoritative Reference Dataset
+
+## Status
+Accepted for V1 research and implementation planning.
+
+## Context
+The Basiskaart Vlaanderen / GRB is a professional Flemish geospatial reference dataset. GeoIntel is scoped to the Kempen, so Flemish official data is highly relevant.
+
+## Decision
+Treat GRB as the primary QA/QC reference where available. Use it for building/reference geometry validation and later for roads, water, and other base-map objects.
+
+V1 integration strategy:
+
+1. Implement a GRB provider abstraction.
+2. Start with WFS or downloaded sample/cache depending on practical availability.
+3. Normalize GRB features into a common `reference_features` model.
+4. Compare AI detections against GRB with IoU/overlap metrics.
+
+## Consequences
+GeoIntel becomes more relevant to real Flemish GeoAI workflows than a generic OSM-only demo. GRB validation becomes a portfolio killer feature.
+
+## Non-goals
+Do not block the entire build on live GRB integration. Provide fixtures and provider interfaces first, then connect real GRB when endpoint details are tested.

adr/ADR-004-storage-strategy.md

@@ -0,0 +1,27 @@
+# ADR-004 — Storage Strategy
+
+## Status
+Accepted for V1.
+
+## Context
+GeoIntel stores multiple artifact types: uploaded rasters, vector uploads, generated tiles, model outputs, masks, exports, and reports.
+
+## Decision
+Use local filesystem storage for V1 with a strict directory convention:
+
+- `storage/uploads/` for original user uploads,
+- `storage/originals/` for normalized source copies,
+- `storage/tiles/` for generated raster tiles,
+- `storage/masks/` for segmentation masks,
+- `storage/derived/` for processed artifacts,
+- `storage/exports/` for GeoJSON/COCO/YOLO exports,
+- `storage/reports/` for reports,
+- `storage/models/` for model artifacts.
+
+Database rows reference files by relative path and content hash.
+
+## Consequences
+Simple local development and predictable repo behavior. Future MinIO/S3 migration remains possible because storage calls must go through a service boundary.
+
+## Non-goals
+No direct random file writes from routes or frontend-specific paths.

adr/ADR-005-ai-model-strategy.md

@@ -0,0 +1,18 @@
+# ADR-005 — AI Model Strategy
+
+## Status
+Accepted for V1.
+
+## Context
+The vacancy emphasizes PyTorch, object detection, segmentation, and GeoAI. A portfolio build should show a real inference pipeline, not only AI text generation.
+
+## Decision
+Use Ultralytics YOLO as the first object detection runtime because it is practical, PyTorch-based, well documented, and fast to integrate. Add segmentation through YOLO-seg or SAM after the detection pipeline is reliable.
+
+Model execution must be wrapped behind `ModelRegistryService` and `DetectionService` interfaces so the UI and API do not depend directly on Ultralytics internals.
+
+## Consequences
+GeoIntel can demonstrate model inference, georeferencing, output conversion, confidence thresholds, and QA/QC against GRB.
+
+## Non-goals
+Do not train a custom model in V1. Fine-tuning becomes V2/V3 after annotation and dataset export exist.

adr/ADR-006-job-processing.md

@@ -0,0 +1,25 @@
+# ADR-006 — Job Processing
+
+## Status
+Accepted for V1.
+
+## Context
+Raster tiling, detection, segmentation, QA, and exports can take longer than a normal HTTP request.
+
+## Decision
+Use Redis + RQ for V1 background jobs. Every long-running operation creates an `analysis_run` or `job` record, updates status, stores outputs, and emits events.
+
+Supported statuses:
+
+- pending,
+- queued,
+- running,
+- completed,
+- failed,
+- cancelled.
+
+## Consequences
+The UI can show progress and status without blocking. RQ is easier than Celery for an initial solo/portfolio project.
+
+## Non-goals
+No Kubernetes-native queues, no Airflow, no full workflow engine in V1.

adr/ADR-007-api-design.md

@@ -0,0 +1,28 @@
+# ADR-007 — API Design
+
+## Status
+Accepted for V1.
+
+## Context
+The frontend must be API-driven and Codex must not invent inconsistent response shapes.
+
+## Decision
+Use REST-style FastAPI endpoints with typed Pydantic schemas. Responses use stable envelopes for long-running jobs and direct resources for simple CRUD operations.
+
+Errors use a common structure:
+
+```json
+{
+  "error": {
+    "code": "DATASET_NOT_FOUND",
+    "message": "Dataset not found.",
+    "details": {}
+  }
+}
+```
+
+## Consequences
+Frontend API clients, tests, and docs stay consistent.
+
+## Non-goals
+No GraphQL in V1.