feat: wire up indicator map layers on results dashboard

Spatial indicators (cropland, vegetation, water) now cache their 2D
raster data after processing. The worker generates styled PNG maps via
render_indicator_map(), served through a new API endpoint. The frontend
overlays these on the results map when clicking indicator cards.

- Add SpatialData dataclass and get_spatial_data() to BaseIndicator
- Cache NDVI/MNDWI grids in cropland, vegetation, water indicators
- Worker generates map PNGs alongside charts during job processing
- New GET /api/jobs/{job_id}/maps/{indicator_id} endpoint
- Frontend: MapLibre image overlay with graceful fallback for non-spatial indicators
- Fix setuptools package discovery in pyproject.toml

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

app/indicators/base.py

@@ -1,9 +1,24 @@
 from __future__ import annotations
 
 import abc
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
 from app.models import AOI, TimeRange, IndicatorResult, IndicatorMeta
 
 
+@dataclass
+class SpatialData:
+    """Raster data produced by an indicator for map rendering."""
+    data: np.ndarray        # 2-D array (lats, lons)
+    lons: np.ndarray        # 1-D longitude coordinates
+    lats: np.ndarray        # 1-D latitude coordinates
+    label: str = ""         # colorbar label
+    colormap: str = "RdYlGn"
+
+
 class BaseIndicator(abc.ABC):
     id: str
     name: str
@@ -11,6 +26,8 @@ class BaseIndicator(abc.ABC):
     question: str
     estimated_minutes: int
 
+    _spatial_data: Optional[SpatialData] = None
+
     def meta(self) -> IndicatorMeta:
         return IndicatorMeta(
             id=self.id,
@@ -24,6 +41,10 @@ class BaseIndicator(abc.ABC):
     async def process(self, aoi: AOI, time_range: TimeRange) -> IndicatorResult:
         ...
 
+    def get_spatial_data(self) -> Optional[SpatialData]:
+        """Return cached spatial data from the last process() call, or None."""
+        return self._spatial_data
+
 
 class IndicatorRegistry:
     def __init__(self) -> None:

app/indicators/cropland.py

@@ -5,7 +5,7 @@ from typing import Any
 
 import numpy as np
 
-from app.indicators.base import BaseIndicator
+from app.indicators.base import BaseIndicator, SpatialData
 from app.models import (
     AOI,
     TimeRange,
@@ -30,6 +30,17 @@ class CroplandIndicator(BaseIndicator):
     async def process(self, aoi: AOI, time_range: TimeRange) -> IndicatorResult:
         baseline_ndvi, current_ndvi = await self._fetch_ndvi_composite(aoi, time_range)
 
+        # Cache spatial data for map rendering
+        rows, cols = current_ndvi.shape
+        min_lon, min_lat, max_lon, max_lat = aoi.bbox
+        self._spatial_data = SpatialData(
+            data=current_ndvi,
+            lons=np.linspace(min_lon, max_lon, cols),
+            lats=np.linspace(max_lat, min_lat, rows),
+            label="Peak-season NDVI",
+            colormap="RdYlGn",
+        )
+
         baseline_mean = float(np.nanmean(baseline_ndvi))
         current_mean = float(np.nanmean(current_ndvi))
 

app/indicators/vegetation.py

@@ -5,7 +5,7 @@ from typing import Any
 
 import numpy as np
 
-from app.indicators.base import BaseIndicator
+from app.indicators.base import BaseIndicator, SpatialData
 from app.models import (
     AOI,
     TimeRange,
@@ -28,6 +28,17 @@ class VegetationIndicator(BaseIndicator):
     async def process(self, aoi: AOI, time_range: TimeRange) -> IndicatorResult:
         baseline_ndvi, current_ndvi = await self._fetch_ndvi_composite(aoi, time_range)
 
+        # Cache spatial data for map rendering
+        rows, cols = current_ndvi.shape
+        min_lon, min_lat, max_lon, max_lat = aoi.bbox
+        self._spatial_data = SpatialData(
+            data=current_ndvi,
+            lons=np.linspace(min_lon, max_lon, cols),
+            lats=np.linspace(max_lat, min_lat, rows),
+            label="Mean NDVI",
+            colormap="RdYlGn",
+        )
+
         baseline_mean = float(np.nanmean(baseline_ndvi))
         current_mean = float(np.nanmean(current_ndvi))
 

app/indicators/water.py

@@ -5,7 +5,7 @@ from typing import Any
 
 import numpy as np
 
-from app.indicators.base import BaseIndicator
+from app.indicators.base import BaseIndicator, SpatialData
 from app.models import (
     AOI,
     TimeRange,
@@ -29,6 +29,17 @@ class WaterIndicator(BaseIndicator):
     async def process(self, aoi: AOI, time_range: TimeRange) -> IndicatorResult:
         baseline_mndwi, current_mndwi = await self._fetch_mndwi_composite(aoi, time_range)
 
+        # Cache spatial data for map rendering
+        rows, cols = current_mndwi.shape
+        min_lon, min_lat, max_lon, max_lat = aoi.bbox
+        self._spatial_data = SpatialData(
+            data=current_mndwi,
+            lons=np.linspace(min_lon, max_lon, cols),
+            lats=np.linspace(max_lat, min_lat, rows),
+            label="MNDWI",
+            colormap="RdBu",
+        )
+
         baseline_water = float(np.nanmean(baseline_mndwi > MNDWI_THRESHOLD))
         current_water = float(np.nanmean(current_mndwi > MNDWI_THRESHOLD))
 

app/main.py

@@ -69,6 +69,16 @@ def create_app(db_path: str = "aperture.db", run_worker: bool = False) -> FastAP
             filename=f"aperture_package_{job_id}.zip",
         )
 
+    @app.get("/api/jobs/{job_id}/maps/{indicator_id}")
+    async def get_indicator_map(job_id: str, indicator_id: str):
+        map_path = _HERE.parent / "results" / job_id / f"{indicator_id}_map.png"
+        if not map_path.exists():
+            raise HTTPException(status_code=404, detail="Map not available for this indicator")
+        return FileResponse(
+            path=str(map_path),
+            media_type="image/png",
+        )
+
     # ── Static files + SPA root ───────────────────────────────────────
     if _FRONTEND_DIR.exists():
         app.mount("/static", StaticFiles(directory=str(_FRONTEND_DIR)), name="static")

app/worker.py

@@ -9,6 +9,7 @@ from app.models import JobStatus
 from app.outputs.report import generate_pdf_report
 from app.outputs.package import create_data_package
 from app.outputs.charts import render_timeseries_chart
+from app.outputs.maps import render_indicator_map
 from app.core.email import send_completion_email
 
 logger = logging.getLogger(__name__)
@@ -21,12 +22,22 @@ async def process_job(job_id: str, db: Database, registry: IndicatorRegistry) ->
         return
     await db.update_job_status(job_id, JobStatus.PROCESSING)
     try:
+        # Track spatial data per indicator for map generation
+        spatial_cache = {}
+
         for indicator_id in job.request.indicator_ids:
             await db.update_job_progress(job_id, indicator_id, "processing")
             indicator = registry.get(indicator_id)
             result = await indicator.process(job.request.aoi, job.request.time_range)
+
+            # Capture spatial data before it's lost
+            spatial = indicator.get_spatial_data()
+            if spatial is not None:
+                spatial_cache[indicator_id] = spatial
+
             await db.save_job_result(job_id, result)
             await db.update_job_progress(job_id, indicator_id, "complete")
+
         # Generate outputs
         job = await db.get_job(job_id)
         results_dir = os.path.join("results", job_id)
@@ -34,7 +45,7 @@ async def process_job(job_id: str, db: Database, registry: IndicatorRegistry) ->
 
         output_files = []
 
-        # Generate charts for each result
+        # Generate charts and maps for each result
         for result in job.results:
             chart_path = os.path.join(results_dir, f"{result.indicator_id}_chart.png")
             render_timeseries_chart(
@@ -46,6 +57,23 @@ async def process_job(job_id: str, db: Database, registry: IndicatorRegistry) ->
             )
             output_files.append(chart_path)
 
+            # Generate map PNG if spatial data is available
+            spatial = spatial_cache.get(result.indicator_id)
+            if spatial is not None:
+                map_path = os.path.join(results_dir, f"{result.indicator_id}_map.png")
+                render_indicator_map(
+                    data=spatial.data,
+                    lons=spatial.lons,
+                    lats=spatial.lats,
+                    aoi=job.request.aoi,
+                    indicator_name=result.indicator_id.replace("_", " ").title(),
+                    status=result.status,
+                    output_path=map_path,
+                    colormap=spatial.colormap,
+                    label=spatial.label,
+                )
+                output_files.append(map_path)
+
         # Generate PDF report
         report_path = os.path.join(results_dir, "report.pdf")
         generate_pdf_report(

frontend/js/api.js

@@ -81,3 +81,13 @@ export function reportUrl(jobId) {
 export function packageUrl(jobId) {
   return `${BASE}/api/jobs/${jobId}/package`;
 }
+
+/**
+ * Returns the URL for an indicator map PNG.
+ * @param {string} jobId
+ * @param {string} indicatorId
+ * @returns {string}
+ */
+export function mapUrl(jobId, indicatorId) {
+  return `${BASE}/api/jobs/${jobId}/maps/${indicatorId}`;
+}

frontend/js/app.js

@@ -295,7 +295,7 @@ function setupResults() {
     return;
   }
 
-  renderResults(panelEl, footerEl, job.results || [], state.jobId);
+  renderResults(panelEl, footerEl, job.results || [], state.jobId, state.aoi?.bbox);
 
   if (!_resultsMapInit && state.aoi?.bbox) {
     _resultsMapInit = true;

frontend/js/map.js

@@ -179,6 +179,53 @@ export function initResultsMap(containerId, bbox) {
   });
 }
 
+/**
+ * Show an indicator map image overlay on the results map.
+ * @param {string} imageUrl - URL to the map PNG
+ * @param {Array<number>} bbox - [minLon, minLat, maxLon, maxLat]
+ */
+export function showMapOverlay(imageUrl, bbox) {
+  if (!_resultsMap) return;
+
+  const sourceId = 'indicator-overlay';
+  const layerId = 'indicator-overlay-layer';
+
+  // Remove existing overlay
+  if (_resultsMap.getLayer(layerId)) _resultsMap.removeLayer(layerId);
+  if (_resultsMap.getSource(sourceId)) _resultsMap.removeSource(sourceId);
+
+  const [minLon, minLat, maxLon, maxLat] = bbox;
+
+  _resultsMap.addSource(sourceId, {
+    type: 'image',
+    url: imageUrl,
+    coordinates: [
+      [minLon, maxLat],  // top-left
+      [maxLon, maxLat],  // top-right
+      [maxLon, minLat],  // bottom-right
+      [minLon, minLat],  // bottom-left
+    ],
+  });
+
+  _resultsMap.addLayer({
+    id: layerId,
+    type: 'raster',
+    source: sourceId,
+    paint: { 'raster-opacity': 0.85 },
+  }, 'aoi-fill');  // insert below AOI layers
+}
+
+/**
+ * Remove any indicator map overlay from the results map.
+ */
+export function clearMapOverlay() {
+  if (!_resultsMap) return;
+  const sourceId = 'indicator-overlay';
+  const layerId = 'indicator-overlay-layer';
+  if (_resultsMap.getLayer(layerId)) _resultsMap.removeLayer(layerId);
+  if (_resultsMap.getSource(sourceId)) _resultsMap.removeSource(sourceId);
+}
+
 function bboxToPolygon(bbox) {
   const [minLon, minLat, maxLon, maxLat] = bbox;
   return {

frontend/js/results.js

@@ -3,7 +3,11 @@
  * Renders indicator result cards and manages the active-card state.
  */
 
-import { reportUrl, packageUrl } from './api.js';
+import { reportUrl, packageUrl, mapUrl } from './api.js';
+import { showMapOverlay, clearMapOverlay } from './map.js';
+
+let _currentJobId = null;
+let _currentBbox = null;
 
 /**
  * Populate the results panel with indicator result cards.
@@ -11,8 +15,11 @@ import { reportUrl, packageUrl } from './api.js';
  * @param {HTMLElement} footerEl - Footer with download links
  * @param {Array}       results  - Array of IndicatorResult objects
  * @param {string}      jobId    - Job ID (for download links)
+ * @param {Array<number>} bbox   - AOI bounding box for map overlays
  */
-export function renderResults(panelEl, footerEl, results, jobId) {
+export function renderResults(panelEl, footerEl, results, jobId, bbox) {
+  _currentJobId = jobId;
+  _currentBbox = bbox;
   panelEl.innerHTML = '';
 
   if (!results.length) {
@@ -28,9 +35,12 @@ export function renderResults(panelEl, footerEl, results, jobId) {
     panelEl.appendChild(card);
   }
 
-  // Activate first card by default
+  // Activate first card by default and show its map
   const first = panelEl.querySelector('.result-card');
-  if (first) first.classList.add('active');
+  if (first) {
+    first.classList.add('active');
+    _showMapForIndicator(first.dataset.indicatorId);
+  }
 
   // Download links
   footerEl.innerHTML = `
@@ -69,6 +79,7 @@ function _buildResultCard(result) {
     const panel = card.closest('.results-panel-body');
     panel.querySelectorAll('.result-card').forEach(c => c.classList.remove('active'));
     card.classList.add('active');
+    _showMapForIndicator(result.indicator_id);
   });
 
   card.addEventListener('keydown', (e) => {
@@ -107,3 +118,16 @@ function _esc(str) {
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;');
 }
+
+function _showMapForIndicator(indicatorId) {
+  if (!_currentJobId || !_currentBbox) return;
+  const url = mapUrl(_currentJobId, indicatorId);
+  // Check if map exists before showing overlay
+  fetch(url, { method: 'HEAD' }).then(res => {
+    if (res.ok) {
+      showMapOverlay(url, _currentBbox);
+    } else {
+      clearMapOverlay();
+    }
+  }).catch(() => clearMapOverlay());
+}

pyproject.toml

@@ -31,6 +31,9 @@ dev = [
     "pytest-httpx>=0.30.0",
 ]
 
+[tool.setuptools.packages.find]
+include = ["app*"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]