heloha/TODO.md

Project Heloha

A unified, multi-radar severe weather analysis and alerting platform for Oklahoma.

---

Phase 0: Foundation & Setup ✅

• Git repo, .gitignore, README.md
• Go module (github.com/blakeridgway/heloha), standard project layout
• go-chi/chi HTTP router with middleware
• /healthz endpoint
• Makefile with build, run, test, tidy

---

Phase 1: Single Radar Ingestion & Display ✅

Approach changed from AWS S3 → NWS public FTP (tgftp.nws.noaa.gov). No credentials required.

• Fetch latest Level 3 N0Q (Digital Base Reflectivity 0.5°) via HTTP from NWS FTP
• Parse NEXRAD Level 3 ICD-2620001 binary (WMO header strip, bzip2 Symbology Block, Packet 16 radials)
• Web Mercator tile renderer with bilinear interpolation between radials and range bins
• In-memory tile cache (sync.RWMutex map), invalidated on each ingest cycle
• Leaflet.js frontend centered on Oklahoma, dark CartoDB basemap
• HUD with site label, scan time, UTC + CDT live clock
• dBZ color legend
• 20 dBZ minimum threshold + 4-pass speckle filter to suppress AP/biological noise

---

Phase 2: Multi-Radar Fusion ✅

Nearest-radar compositing done per-pixel at tile render time — no pre-built mosaic grid needed.

• 15 NEXRAD sites (OK, TX, KS, AR, MO, LA) ingested concurrently every 2 minutes
• Per-site, per-product ring buffer (12 frames of history)
• Composite tile endpoint: nearest radar per pixel within 230 km range
• NWS active warnings overlay (GeoJSON from api.weather.gov, auto-refreshes every 2 min)
• Range rings (100 / 200 km) and site markers with tooltips on all 15 sites
• Loop animation: scrubber + play/pause, 500 ms/frame, builds up to 12 frames (~24 min)
• REFL / VEL product toggle (velocity infrastructure built; NWS FTP returns 403 for p99r0)
• Leaflet scale bar

---

Phase 3: Advanced Analysis & Alerting

Goal: Find the "so what?" — identify, track, and score dangerous storms.

• Storm Cell Identification (/internal/analysis/segmentation.go)
  • Flood-fill or connected-components blob detection on composite reflectivity
  • Output: list of StormCell objects with bounding polygon, centroid, max dBZ
• Storm Tracking (/internal/analysis/tracking.go)
  • Frame-to-frame centroid correlation to assign persistent TrackID
  • Store per-track history: location, time, intensity, motion vector
• Velocity Source
  • Investigate alternative velocity product paths on NWS FTP (NWS 403 on DS.p99r0)
  • Or ingest Level 2 data from noaa-nexrad-level2 S3 (requester-pays, need creds)
  • Parse velocity, ZDR, CC fields once a source is confirmed
• Signature Detection (/internal/analysis/signatures.go)
  • TVS detector: strong inbound/outbound velocity couplet within a cell
  • Hail core detector: dBZ > 55 co-located with low CC and near-zero ZDR
• Threat Engine (/internal/analysis/threats.go)
  • Threat struct: TrackID, type, severity, predicted path GeoJSON
  • Rules engine: TVS + intensity threshold → tornado threat object
  • Extrapolate predicted path from recent motion vector

---

Phase 4: Frontend Refinement

Goal: Make the analysis actionable in the UI.

• Storm list sidebar (HTMX, refreshes every 15 s)
• Storm detail panel on click (centroid, max dBZ, motion, TVS flag)
• Map overlay: GeoJSON storm polygons + predicted track line
• Pan/zoom to selected storm on sidebar click
• Address search bar with geocoding → drop pin on map
• Opacity slider for radar overlay
• Mobile-responsive layout

---

Phase 5: SRE & Productionization

• Multi-stage Dockerfile (build → distroless)
• docker-compose.yml with Prometheus scraping /metrics
• Prometheus metrics: radar_files_processed_total, data_latency_seconds, active_threats_gauge
• Readiness probe: fail if no radar data ingested in last 10 min
• Alertmanager rules: RadarFeedDown, HighProcessingLatency, AppDown
• Config file (config.yaml or env vars) for site list, thresholds, ports

---

Backlog / Future Ideas

• Oklahoma Mesonet integration (ground-level wind, pressure, temp)
• Database persistence for storm tracks (TimescaleDB or PostGIS)
• WebSocket push notifications for threats near a user's location
• ML model trained on historical radar + confirmed tornado reports
• Animate warning polygon borders (pulsing CSS) for active tornado warnings
• Multi-tilt display (0.5°, 1.5°, 2.5°) — currently fixed at 0.5°