Metadata-Version: 2.4
Name: hazard-georeport
Version: 0.1.0
Summary: GeoReport CMS — A CMS-driven geospatial report generation platform powered by Wagtail/Django.
Project-URL: Homepage, https://github.com/icpac-igad/Geo-Report
Project-URL: Repository, https://github.com/icpac-igad/Geo-Report
Project-URL: Issues, https://github.com/icpac-igad/Geo-Report/issues
Author-email: Hillary Koros <koroshillary12@gmail.com>
Maintainer-email: Hillary Koros <koroshillary12@gmail.com>
License: GPL-3.0
License-File: LICENSE
Keywords: charts,climate,cms,dashboard,django,drought,early-warning,flood,geospatial,gis,hazard,maps,report,wagtail
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Wagtail
Classifier: Framework :: Wagtail :: 7
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Requires-Dist: django-cors-headers>=4.9
Requires-Dist: django>=5.2
Requires-Dist: djangorestframework>=3.16
Requires-Dist: wagtail>=7.3
Requires-Dist: whitenoise>=6.12
Provides-Extra: all
Requires-Dist: georeport[dev,production]; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-django>=4.9; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
Provides-Extra: production
Requires-Dist: gunicorn>=25.1; extra == 'production'
Requires-Dist: psycopg2-binary>=2.9; extra == 'production'
Description-Content-Type: text/markdown

# GeoReport

**Hazard-agnostic geospatial report engine for early warning systems.**

An installable Wagtail/Django package that generates CMS-driven geospatial analysis dashboards and bulletins. Configure once for any hazard — drought, flood, locust, food security, climate — no code changes needed.

[![PyPI](https://img.shields.io/pypi/v/hazard-georeport)](https://pypi.org/project/hazard-georeport/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![Django 5.2+](https://img.shields.io/badge/django-5.2%2B-green)](https://www.djangoproject.com/)
[![Wagtail 7.x](https://img.shields.io/badge/wagtail-7.x-teal)](https://wagtail.org/)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-orange)](LICENSE)

## Why GeoReport?

Early warning systems need reporting dashboards. Building one from scratch means months of work — models, views, charts, maps, PDF export, CMS admin. GeoReport gives you all of that as a `pip install`, fully configurable through the Wagtail admin.

**One package, any hazard:**

| Hazard | Phases | Maps | Metrics |
|--------|--------|------|---------|
| Drought | Normal → Watch → Warning → Alert → Emergency | SPI, NDVI, Land Cover | Rainfall, Temperature, Soil Moisture, NDVI |
| Flood | Low → Moderate → High → Very High → Extreme | Flood extent, River levels | Precipitation, River discharge, Affected area |
| Locust | Calm → Outbreak → Upsurge → Plague | Breeding sites, Swarm tracks | Egg laying, Hopper bands, Swarm count |
| Food Security | IPC 1 → 2 → 3 → 4 → 5 | Food insecurity, Market prices | Population affected, GAM, SAM |
| *Your hazard* | *Configure in CMS* | *Any WMS/XYZ/GeoJSON* | *Any indicator* |

## Features

- **CMS-driven** — all content managed through Wagtail admin, zero code changes
- **10 chart types** — exposure analysis, time series, climate trends, vegetation indices
- **Cartographic map figures** — configurable legends, scale bars, north arrows, attribution
- **6 map layer types** — WMS, XYZ, vector tiles, GeoJSON, COG, heatmap
- **Native PDF export** — jsPDF vector rendering, not screenshots
- **PNG export** — html2canvas at 3x resolution with watermarks
- **Bulletin system** — auth-gated advisory bulletins with expert commentary
- **REST API** — Django REST Framework endpoints for dashboard configuration
- **No npm/node** — pure server-rendered templates + vanilla JS via CDN
- **Dockerized** — PostGIS + Gunicorn, single `docker compose up`

## Install

```bash
pip install hazard-georeport
# or
uv add hazard-georeport
```

Add to your Django project:

```python
# settings.py
INSTALLED_APPS = [
    "georeport.dashboard",
    "wagtail.contrib.settings",
    "wagtail.snippets",
    "wagtail",
    "rest_framework",
    "corsheaders",
    # ... your other apps
]

# urls.py
from django.urls import path, include

urlpatterns = [
    path("", include("georeport.urls")),
    # ... wagtail, admin, etc.
]
```

Then migrate and seed:

```bash
python manage.py migrate
python manage.py seed_default_config
```

## Quick Start (Demo Project)

```bash
git clone https://github.com/icpac-igad/Geo-Report.git
cd Geo-Report
uv sync

python sandbox/manage.py migrate --run-syncdb --settings=sandbox.settings.dev
python sandbox/manage.py seed_default_config --settings=sandbox.settings.dev
python sandbox/manage.py createsuperuser --settings=sandbox.settings.dev
python sandbox/manage.py runserver 0.0.0.0:8000 --settings=sandbox.settings.dev
```

Open http://localhost:8000 (dashboard) or http://localhost:8000/cms/ (admin).

### Docker

```bash
cd sandbox
docker compose up --build
```

| Service | URL |
|---------|-----|
| Dashboard | http://localhost:9101 |
| Wagtail Admin | http://localhost:9101/cms/ |

## CMS Configuration

Everything is configured through the Wagtail admin — no code changes needed.

### Settings (Site-wide)

| Model | What It Configures |
|-------|--------------------|
| **DashboardSettings** | Title, organization, logo, primary color, copyright text |
| **TimeConfiguration** | Period cycles (dekadal, monthly, seasonal), available years, seasons |

### Snippets (Collections)

| Model | What It Configures |
|-------|--------------------|
| **HazardPhase** | Severity levels — name, color, sort order (e.g., Watch → Alert → Emergency) |
| **Region** + admin levels | Geographic hierarchy — countries and admin boundaries |
| **MetricConfig** | Key indicator cards — title, unit, icon, value range |
| **ChartConfig** | Which charts to show — enable/disable, custom titles |
| **MapSection** | Map panels — layer type, data URL, legend entries, attribution |
| **HydroBasin** + levels | Hydrological basin hierarchy |
| **Cluster** | Country groupings for regional analysis |
| **AreaType** | Available spatial selection modes |
| **FooterAction** | Action buttons — export PDF, export PNG, share, view bulletin |
| **ExtendedTag** | Categorized tags for indicators |
| **BulletinConfig** | Bulletin content — expert comments, sections, outlook |

### Map Layers

Each `MapSection` supports:

| Layer Type | Use Case |
|-----------|----------|
| WMS | GeoServer/MapServer layers (SPI, NDVI, flood extent) |
| XYZ | Standard tile servers |
| Vector Tiles | MVT/PBF sources |
| GeoJSON | Feature data from APIs |
| COG | Cloud Optimized GeoTIFFs |
| Heatmap | Point density visualization |

Configure legend entries as JSON:
```json
[
  {"color": "#006400", "label": "Very High"},
  {"color": "#FFD700", "label": "Moderate"},
  {"color": "#8B0000", "label": "Very Low"}
]
```

## Architecture

```
georeport/                    # Installable package
├── dashboard/                # Django app (app_label="dashboard")
│   ├── models.py             # 15 Wagtail CMS models
│   ├── views.py              # Dashboard + bulletin views
│   ├── api.py                # DRF REST API
│   ├── serializers.py        # API serialization
│   ├── templates/            # Server-rendered HTML
│   ├── static/
│   │   ├── css/report.css    # Single stylesheet, CSS custom properties
│   │   └── js/
│   │       ├── dashboard.js  # Interactions, AOI drawing, PDF/PNG export
│   │       ├── charts.js     # Chart.js factory (10 chart types)
│   │       └── maps.js       # Map figure rendering + cartographic elements
│   └── management/commands/  # seed_default_config, load_gadm
└── urls.py                   # Package routes
```

### Frontend Stack (CDN — no build step)

| Library | Version | Purpose |
|---------|---------|---------|
| Chart.js | 4.4.7 | All charts |
| MapLibre GL JS | 4.7.1 | Map rendering |
| html2canvas | 1.4.1 | PNG export |
| jsPDF | 2.5.2 | PDF export |

## Roadmap

- [x] Installable package with Wagtail CMS
- [x] Hazard-agnostic naming and configuration
- [x] Cartographic map figures with legends
- [x] Native PDF/PNG export
- [x] Bulletin system
- [x] REST API (Django REST Framework)
- [ ] **Data Provider interface** — connect live APIs (CHIRPS, MODIS, ERA5)
- [ ] **Dynamic chart groups** — DB-driven chart grouping
- [ ] **Seed profiles** — `drought.json`, `flood.json`, `minimal.json`
- [ ] **PyPI release** — versioned package on PyPI
- [ ] **Tests & CI/CD** — unit tests, GitHub Actions
- [ ] **Documentation site** — full docs with examples

## Contributing

1. Clone and run the demo project (see Quick Start)
2. Explore the dashboard and CMS admin
3. Open [issues](https://github.com/icpac-igad/Geo-Report/issues) for bugs or ideas
4. Submit pull requests against `main`

## License

[GPL-3.0](LICENSE)
