bluegreencity-ki

Documentation Overview

This directory contains the project documentation intended for publication and team handover. The material is structured so that scientific methodology, system operation, and maintenance workflows are separated clearly. Most documents are written in English; some operational, maintenance, and validation documents are in German.

Quick Start

1. How to run the Tool — end-to-end execution workflow
2. Pipeline Workflow — pipeline flowchart, input data overview, and enrichment modules
3. Data Flow Overview — end-to-end chain from tree inventory to irrigation plan (for non-developers and partner handover)
4. Configuration — complete reference of every config/config.yaml key
5. ML Risk Assessment — current ML methodology, feature reference, reports, and archive

Core Guides

• Risk Criteria Overview — documented criteria and registered variants
• ML Methodology Story (Der Faden) — continuous methodology thread from raw data to the operational product, with Grafana/doc navigation (for partner communication and review)
• ML Risk Assessment Guide — operative training, inference, and outputs
• Validation and Current Operational ML Paths — fixed temporal evidence path, latest-inventory inference, and overnight v4 refresh
• Static Risk Scoring Guide — weighting, normalization, aggregation, and interpretation
• Validation — validation metrics, grouped CV, and benchmark paths

Compliance

• EU AI Act Assessment — risk classification (Limited Risk), transparency obligations (Art. 50), human oversight, data governance, and GDPR relevance

Deeper Reference

• Architecture — system architecture, design patterns, and extension points
• Criteria & Features Cross-Reference — all features with rule-based and AutoML usage flags
• Static Weighting Comparison — active 55/45 weighting and experimental comparison against monotone and ML variants
• ML Documentation Overview — entry point for guides, reports, and archive
• AutoML Feature Reference — feature documentation for the current September 2026 operational model (35 features); the current operative feature set is defined in config/config.yaml (feature_columns)
• Treelife Overlap Validation Report — external validation of the October 2026 retraining against real LHH Treelife interventions (issue #257)
• Operational Panel Grouped CV Report — current internal robustness check with 5-fold grouped cross-validation by objectid (September 2026 retraining round; the June 2026 report is archived)
• Operational Panel Result Report — historical April 2026 reference: model vs. baseline and minimal, 2024→2025 backtest
• Baseline vs. Minimal Dashboard Comparison — model validation, feature shifts, and 2025 output differences
• High-Risk Feature Combinations — feature combinations behind the highest predicted ML risk scores
• Stable AutoML Ablation Report — historical reference: stable AutoGluon benchmark and feature-ablation variants
• 2018–2024 Training & 2025 Verification — historical reference: initial training run and pipeline verification
• Plausibility — automated plausibility checks during pipeline runs
• Irrigation Weight Sensitivity (2026-09-26) — Phase 3b replay of the planning policy on pinned 2026 summer state days
• ADR Overview — documented design decisions and their rationale

Technical and Operational Documentation

• postgis/PostGIS_Installation.md - Administrator guide for deploying PostgreSQL/PostGIS with Docker
• postgis/PostGIS_and_QGIS_User_Guide.md - User guide for database access from DBeaver, VS Code, Python, QGIS, and pgAdmin
• postgis/DBeaver_Setup_Guide.md - Focused setup guide for DBeaver users
• postgis/Data_Import_Guide.md - Import workflows for raster and climate data
• postgis/wfs_service.md - WFS service sharing current tree data (AutoML risk scores + SWBM) with partners via QWC
• workstation/Workstation_Remote_Development.md - Reproducible remote-development setup for the shared workstation
• workstation/Infrastructure_Overview.md - Infrastructure overview for the workstation environment
• workstation/LLM_Setup_Guide.md - Local LLM setup with vLLM (Qwen3.8-27B) as the primary server, plus Copilot/KiloCode/AnythingLLM/Open WebUI integration and performance tuning notes
• workstation/Superset_Setup_Guide.md - Administrator guide for installing Apache Superset on the workstation and exposing it via Tailscale HTTPS
• workstation/backup_strategy.md - Backup approach and operational safeguards

Maintenance Documentation

• data_maintenance/README.md - Overview of recurring maintenance workflows
• data_maintenance/Tree_Inventory_Import.md - Runtime import flow and domain handling of the Hannover tree inventory CSV
• data_maintenance/Tree_Inventory_Status_Matrix.md - Status taxonomy for planned, removed, placeholder, and analysable tree records
• data_maintenance/Baumkataster_v6_Diskrepanz.md - v6 inventory count discrepancy vs. LHH figures (raw rows vs. filtered trees), one-off note
• data_maintenance/Climate_Data_Import.md - DWD climate data import (HYRAS, HOSTRADA, evaporation) into PostGIS
• data_maintenance/Tree_Year_Analysis.md - Reproducible Baum-Jahr cache, t/t+1 semantics, identity matching, and refresh workflow
• water_balance/README.md - SWBM 7-day forecast: real forecast rows, continuation anchoring, observed-row consumers, and day-of-year sunlit hours
• water_balance/capillary_rise.md - Capillary rise: kriged median groundwater depth (Flurabstand) surface, swbm-v0.3
• data_maintenance/Soil_Water_Balance_Integration.md - Daily SWBM integration contract, irrigation events, persistence, and calibration boundary
• data_maintenance/Model_Parameter_Uebersicht_2026-09-16.md - Code-verified snapshot of all exact parameters in the SWBM, ML, and rule-based models (2026-09-16; the 2026-08-29 snapshot is archived under risk_assessment_ml/archive/)
• data_maintenance/Irrigation_Planning.md - Phase 2 risk/SWBM prioritization, resource optimization, CLI, and persistence
• data_maintenance/Irrigation_Review_Taipy.md - Phase 3 resource scenarios, human review, work orders, and execution feedback
• data_maintenance/enrichment.md - OBSkH and Citree enrichment workflow, matching rules, and QA fields
• data_maintenance/Citree_Species_Extraction.md - Citree species profile extraction via the public AJAX endpoints
• data_maintenance/citree_mapping_review.md - Review backlog for remaining Citree no-match and ambiguous species labels
• data_maintenance/OSM_Highway_Data_Update.md - OSM highway refresh workflow
• data_maintenance/ALKIS_Integration.md - ALKIS cadastral data integration for precise street name matching (salt, street_type)
• backups/PostGIS_Backup_Guide.md - Backup and restore procedure for the database

Historical and Research Material

Historical reports, experiments, and superseded notes remain in the archive and report folders. Use the guides above as the primary entry points for the current operational state.

Research and evaluation documents (dated investigations — not descriptions of the current system):

• BART ML Investigation — feasibility of a BART-based drought model (Jan 2026, awaiting decision)
• GAM XAI Explainability — research concept for GAM-based explainability (prototype, not implemented)
• Knowledge Graphs & Temporal Reasoning — phased PoC proposal (Jan 2026)
• PostgREST API Evaluation — evaluation of a REST API for partner data access
• SEDA/DB vs. DuckDB — spatial database technology evaluation incl. ADR-002

Publication Principles

• Do not publish live credentials, internal passwords, or environment files.
• Prefer placeholders for hostnames, VPN addresses, and service endpoints unless the document is strictly internal.
• Keep scientific explanations detailed enough for reproducibility, but move operational noise and historical detours into separate background documents.