✨ feat(flood): add SurgeInk backend + flood risk visualization

Add Python FastAPI backend (server/) with geocode, forecast, and layers
endpoints. Add frontend flood feature slice with FEMA flood zone overlay
on MapLibre, river discharge sparkline (recharts), risk score card, and
flood data toggles in settings panel. Rebrand header to SurgeInk.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY surgeink/ surgeink/
+
+EXPOSE 8000
+
+CMD ["uvicorn", "surgeink.main:app", "--host", "0.0.0.0", "--port", "8000"]

pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "surgeink"
+version = "0.1.0"
+description = "Flood risk visualization API for SurgeInk"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0,<1.0",
+    "uvicorn[standard]>=0.34.0",
+    "httpx>=0.28.0",
+    "redis[hiredis]>=5.2.0",
+    "pydantic>=2.10.0",
+    "pydantic-settings>=2.7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.115.0,<1.0
+uvicorn[standard]>=0.34.0
+httpx>=0.28.0
+redis[hiredis]>=5.2.0
+pydantic>=2.10.0
+pydantic-settings>=2.7.0

surgeink/api/forecast.py

@@ -0,0 +1,55 @@
+import statistics as stats
+
+from fastapi import APIRouter, HTTPException, Query
+
+from surgeink.data.openmeteo import fetch_flood_forecast
+from surgeink.models.schemas import (
+    ForecastDaily,
+    ForecastResponse,
+    ForecastStatistics,
+)
+
+router = APIRouter()
+
+
+@router.get("/forecast", response_model=ForecastResponse)
+async def get_forecast(
+    lat: float = Query(..., ge=-90, le=90),
+    lng: float = Query(..., ge=-180, le=180),
+    forecast_days: int = Query(7, ge=1, le=210),
+    include_history: int = Query(0, ge=0, le=92),
+):
+    try:
+        data = await fetch_flood_forecast(lat, lng, forecast_days, include_history)
+    except Exception as e:
+        raise HTTPException(502, detail=f"Open-Meteo API error: {e}")
+
+    daily_raw = data.get("daily", [])
+    daily = [ForecastDaily(date=d["date"], discharge_m3s=d["discharge_m3s"]) for d in daily_raw]
+
+    # Current discharge = first value in the list (today or earliest date)
+    current = daily[0].discharge_m3s if daily else None
+
+    # Compute statistics from non-null values
+    values = [d.discharge_m3s for d in daily if d.discharge_m3s is not None]
+    statistics = None
+    if len(values) >= 2:
+        sorted_vals = sorted(values)
+        p75_idx = int(len(sorted_vals) * 0.75)
+        p90_idx = int(len(sorted_vals) * 0.90)
+        statistics = ForecastStatistics(
+            mean=round(stats.mean(values), 2),
+            median=round(stats.median(values), 2),
+            p75=round(sorted_vals[min(p75_idx, len(sorted_vals) - 1)], 2),
+            p90=round(sorted_vals[min(p90_idx, len(sorted_vals) - 1)], 2),
+            period=f"{daily[0].date} to {daily[-1].date}" if daily else "",
+        )
+
+    return ForecastResponse(
+        latitude=data.get("latitude", lat),
+        longitude=data.get("longitude", lng),
+        source="Open-Meteo GloFAS v4",
+        current_discharge_m3s=current,
+        daily=daily,
+        statistics=statistics,
+    )

surgeink/api/geocode.py

@@ -0,0 +1,66 @@
+import httpx
+from fastapi import APIRouter, HTTPException, Query
+
+from surgeink.cache.redis_cache import cache_get_json, cache_set_json
+from surgeink.config import settings
+from surgeink.models.schemas import GeocodeResponse, GeocodeResult
+
+router = APIRouter()
+
+CACHE_TTL = 86400  # 24 hours
+USER_AGENT = "SurgeInk/0.1 (flood-risk-viz)"
+
+
+@router.get("/geocode", response_model=GeocodeResponse)
+async def geocode(
+    q: str = Query(..., min_length=2, description="Search query"),
+    limit: int = Query(5, ge=1, le=10),
+):
+    cache_key = f"geocode:{q.lower().strip()}:{limit}"
+    cached = await cache_get_json(cache_key)
+    if cached is not None:
+        return GeocodeResponse(**cached)
+
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            resp = await client.get(
+                f"{settings.nominatim_base_url}/search",
+                params={
+                    "format": "jsonv2",
+                    "addressdetails": 1,
+                    "limit": limit,
+                    "q": q,
+                },
+                headers={"User-Agent": USER_AGENT},
+            )
+            resp.raise_for_status()
+    except Exception as e:
+        raise HTTPException(502, detail=f"Nominatim API error: {e}")
+
+    raw_results = resp.json()
+    results = []
+
+    for item in raw_results:
+        # Nominatim bbox: [south, north, west, east] as strings
+        # Convert to [min_lng, min_lat, max_lng, max_lat]
+        raw_bbox = item.get("boundingbox", [])
+        if len(raw_bbox) == 4:
+            south, north, west, east = [float(v) for v in raw_bbox]
+            bbox = [west, south, east, north]
+        else:
+            bbox = []
+
+        results.append(GeocodeResult(
+            name=item.get("name", item.get("display_name", "").split(",")[0]),
+            display_name=item.get("display_name", ""),
+            lat=float(item.get("lat", 0)),
+            lng=float(item.get("lon", 0)),
+            bbox=bbox,
+            flood_data_available=True,
+            available_layers=[],
+        ))
+
+    response_data = {"results": [r.model_dump() for r in results]}
+    await cache_set_json(cache_key, response_data, CACHE_TTL)
+
+    return GeocodeResponse(results=results)

surgeink/api/interpret.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter, HTTPException
+
+router = APIRouter()
+
+
+@router.get("/interpret")
+async def get_interpret():
+    raise HTTPException(501, detail="Not implemented yet — Phase 4")

surgeink/api/layers.py

@@ -0,0 +1,97 @@
+from fastapi import APIRouter, HTTPException, Query
+
+from surgeink.models.schemas import (
+    LayerInfo,
+    LayerLegend,
+    LayerLegendStop,
+    LayersResponse,
+)
+
+router = APIRouter()
+
+# Hardcoded layer catalog — Phase 1.
+# Layers are marked available/unavailable based on what's actually implemented.
+# This will become dynamic in Phase 3 (check data availability per bbox).
+
+LAYER_CATALOG = [
+    LayerInfo(
+        id="ml_risk",
+        name="ML Flood Risk Prediction",
+        type="raster",
+        source="SurgeInk ML v1.0",
+        available=False,
+        reason="Not yet implemented — Phase 4",
+        legend=LayerLegend(
+            type="gradient",
+            stops=[
+                LayerLegendStop(value=1, color="#2166ac", label="Low"),
+                LayerLegendStop(value=5, color="#f4a582", label="Moderate"),
+                LayerLegendStop(value=10, color="#b2182b", label="Critical"),
+            ],
+        ),
+    ),
+    LayerInfo(
+        id="jrc_water_occurrence",
+        name="Historical Water Occurrence",
+        type="raster",
+        source="JRC Global Surface Water (1984–2021)",
+        available=False,
+        reason="Not yet implemented — Phase 2",
+    ),
+    LayerInfo(
+        id="live_discharge",
+        name="River Discharge (Live)",
+        type="geojson",
+        source="Open-Meteo / GloFAS v4",
+        endpoint="/api/v1/forecast",
+        available=True,
+    ),
+    LayerInfo(
+        id="fema_zones",
+        name="FEMA Flood Zones",
+        type="vector",
+        source="FEMA NFHL",
+        available=False,
+        region="US only",
+        reason="Not yet implemented — Phase 3",
+    ),
+    LayerInfo(
+        id="wri_aqueduct",
+        name="Climate Flood Risk Scenarios",
+        type="raster",
+        source="WRI Aqueduct Floods (via GEE)",
+        available=False,
+        reason="Not yet implemented — Phase 3",
+    ),
+    LayerInfo(
+        id="interpretability",
+        name="Model Interpretability Heatmap",
+        type="raster",
+        source="SurgeInk ML interpretability",
+        available=False,
+        reason="Not yet implemented — Phase 4",
+    ),
+]
+
+
+@router.get("/layers", response_model=LayersResponse)
+async def get_layers(
+    bbox: str = Query(
+        ...,
+        description="Bounding box: min_lng,min_lat,max_lng,max_lat",
+    ),
+    zoom: int = Query(10, ge=0, le=22),
+):
+    # Parse bbox
+    parts = bbox.split(",")
+    if len(parts) != 4:
+        raise HTTPException(422, detail="bbox must have exactly 4 comma-separated values")
+
+    try:
+        [float(p.strip()) for p in parts]
+    except ValueError:
+        raise HTTPException(422, detail="bbox values must be numeric")
+
+    # For Phase 1, return the full catalog regardless of bbox.
+    # Phase 3 will make availability dynamic based on location.
+    return LayersResponse(layers=LAYER_CATALOG)

surgeink/api/predict.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter, HTTPException
+
+router = APIRouter()
+
+
+@router.post("/predict")
+async def predict():
+    raise HTTPException(501, detail="Not implemented yet — Phase 4")

surgeink/api/risk.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter, HTTPException
+
+router = APIRouter()
+
+
+@router.get("/risk")
+async def get_risk():
+    raise HTTPException(501, detail="Not implemented yet — Phase 3")

surgeink/api/router.py

@@ -0,0 +1,13 @@
+from fastapi import APIRouter
+
+from surgeink.api import geocode, forecast, layers, risk, tiles, predict, interpret
+
+router = APIRouter(prefix="/api/v1")
+
+router.include_router(geocode.router, tags=["geocode"])
+router.include_router(forecast.router, tags=["forecast"])
+router.include_router(layers.router, tags=["layers"])
+router.include_router(risk.router, tags=["risk"])
+router.include_router(tiles.router, tags=["tiles"])
+router.include_router(predict.router, tags=["predict"])
+router.include_router(interpret.router, tags=["interpret"])

surgeink/api/tiles.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter, HTTPException
+
+router = APIRouter()
+
+
+@router.get("/tiles/{layer}/{z}/{x}/{y}.{fmt}")
+async def get_tile(layer: str, z: int, x: int, y: int, fmt: str):
+    raise HTTPException(501, detail="Not implemented yet — Phase 2")

surgeink/cache/redis_cache.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Optional
+
+import redis.asyncio as aioredis
+
+from surgeink.config import settings
+
+logger = logging.getLogger(__name__)
+
+_redis: Optional[aioredis.Redis] = None
+
+
+async def get_redis() -> aioredis.Redis:
+    global _redis
+    if _redis is None:
+        _redis = aioredis.from_url(
+            settings.redis_url,
+            decode_responses=True,
+        )
+    return _redis
+
+
+async def cache_get(key: str) -> Optional[str]:
+    try:
+        r = await get_redis()
+        return await r.get(key)
+    except Exception:
+        logger.debug("Redis cache miss (connection error) for key: %s", key)
+        return None
+
+
+async def cache_set(key: str, value: str, ttl_seconds: int = 3600) -> None:
+    try:
+        r = await get_redis()
+        await r.set(key, value, ex=ttl_seconds)
+    except Exception:
+        logger.debug("Redis cache set failed for key: %s", key)
+
+
+async def cache_get_json(key: str):
+    raw = await cache_get(key)
+    if raw is not None:
+        return json.loads(raw)
+    return None
+
+
+async def cache_set_json(key: str, value, ttl_seconds: int = 3600) -> None:
+    await cache_set(key, json.dumps(value), ttl_seconds)
+
+
+async def close_redis() -> None:
+    global _redis
+    if _redis is not None:
+        await _redis.close()
+        _redis = None

surgeink/config.py

@@ -0,0 +1,31 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="SURGEINK_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    env: str = "development"
+    api_host: str = "0.0.0.0"
+    api_port: int = 8000
+
+    # Redis (uses SURGEINK_REDIS_URL or defaults)
+    redis_url: str = "redis://redis:6379/0"
+
+    # External data source base URLs
+    nominatim_base_url: str = "https://nominatim.openstreetmap.org"
+    openmeteo_base_url: str = "https://flood-api.open-meteo.com"
+    fema_nfhl_base_url: str = "https://hazards.fema.gov/arcgis/rest/services/public/NFHL/MapServer"
+    openfema_base_url: str = "https://www.fema.gov/api/open/v2"
+
+    # CORS
+    cors_origins: list[str] = [
+        "http://localhost:5173",
+        "http://localhost:7200",
+    ]
+
+
+settings = Settings()

surgeink/data/openmeteo.py

@@ -0,0 +1,50 @@
+import httpx
+
+from surgeink.cache.redis_cache import cache_get_json, cache_set_json
+from surgeink.config import settings
+
+CACHE_TTL = 21600  # 6 hours
+
+
+async def fetch_flood_forecast(
+    lat: float,
+    lng: float,
+    forecast_days: int = 7,
+    past_days: int = 0,
+) -> dict:
+    cache_key = f"forecast:{lat:.2f}:{lng:.2f}:{forecast_days}:{past_days}"
+    cached = await cache_get_json(cache_key)
+    if cached is not None:
+        return cached
+
+    params = {
+        "latitude": lat,
+        "longitude": lng,
+        "daily": "river_discharge",
+        "forecast_days": forecast_days,
+        "past_days": past_days,
+    }
+
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        resp = await client.get(
+            f"{settings.openmeteo_base_url}/v1/flood",
+            params=params,
+        )
+        resp.raise_for_status()
+
+    data = resp.json()
+
+    times = data.get("daily", {}).get("time", [])
+    discharges = data.get("daily", {}).get("river_discharge", [])
+
+    result = {
+        "latitude": data.get("latitude", lat),
+        "longitude": data.get("longitude", lng),
+        "daily": [
+            {"date": t, "discharge_m3s": d}
+            for t, d in zip(times, discharges)
+        ],
+    }
+
+    await cache_set_json(cache_key, result, CACHE_TTL)
+    return result

surgeink/main.py

@@ -0,0 +1,42 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from surgeink.cache.redis_cache import close_redis
+from surgeink.config import settings
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    yield
+    await close_redis()
+
+
+app = FastAPI(
+    title="SurgeInk API",
+    version="0.1.0",
+    description="Flood risk visualization API",
+    docs_url="/api/docs",
+    openapi_url="/api/openapi.json",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/api/health")
+async def health():
+    return {"status": "ok"}
+
+
+# Mount versioned API router
+from surgeink.api.router import router as api_router  # noqa: E402
+
+app.include_router(api_router)

surgeink/models/schemas.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+# --- Geocode ---
+
+class GeocodeResult(BaseModel):
+    name: str
+    display_name: str
+    lat: float
+    lng: float
+    bbox: list[float]  # [min_lng, min_lat, max_lng, max_lat]
+    flood_data_available: bool = True
+    available_layers: list[str] = []
+
+
+class GeocodeResponse(BaseModel):
+    results: list[GeocodeResult]
+
+
+# --- Forecast ---
+
+class ForecastDaily(BaseModel):
+    date: str
+    discharge_m3s: Optional[float]
+
+
+class ForecastStatistics(BaseModel):
+    mean: Optional[float]
+    median: Optional[float]
+    p75: Optional[float]
+    p90: Optional[float]
+    period: str
+
+
+class ForecastResponse(BaseModel):
+    latitude: float
+    longitude: float
+    source: str
+    current_discharge_m3s: Optional[float]
+    daily: list[ForecastDaily]
+    statistics: Optional[ForecastStatistics] = None
+
+
+# --- Layers ---
+
+class LayerLegendStop(BaseModel):
+    value: float
+    color: str
+    label: str
+
+
+class LayerLegend(BaseModel):
+    type: str
+    stops: list[LayerLegendStop]
+
+
+class LayerInfo(BaseModel):
+    id: str
+    name: str
+    type: str
+    source: str
+    available: bool
+    tile_url: Optional[str] = None
+    endpoint: Optional[str] = None
+    region: Optional[str] = None
+    legend: Optional[LayerLegend] = None
+    reason: Optional[str] = None
+
+
+class LayersResponse(BaseModel):
+    layers: list[LayerInfo]