# Project Heloha

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

---

## Phase 0: Foundation & Setup ✅

- [x] Git repo, `.gitignore`, `README.md`
- [x] Go module (`github.com/blakeridgway/heloha`), standard project layout
- [x] `go-chi/chi` HTTP router with middleware
- [x] `/healthz` endpoint
- [x] `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.*

- [x] Fetch latest Level 3 N0Q (Digital Base Reflectivity 0.5°) via HTTP from NWS FTP
- [x] Parse NEXRAD Level 3 ICD-2620001 binary (WMO header strip, bzip2 Symbology Block, Packet 16 radials)
- [x] Web Mercator tile renderer with bilinear interpolation between radials and range bins
- [x] In-memory tile cache (`sync.RWMutex` map), invalidated on each ingest cycle
- [x] Leaflet.js frontend centered on Oklahoma, dark CartoDB basemap
- [x] HUD with site label, scan time, UTC + CDT live clock
- [x] dBZ color legend
- [x] 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.*

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