🌡️ HeatShift: Plan Around the Heat

Live demo: https://heatshift-seven.vercel.app

HeatShift turns FortyGuard's hyperlocal urban temperature archive into something no heatmap dashboard gives a working crew: a decision. Drop your job sites on a map, and HeatShift ranks the day's daylight work windows coolest-to-hottest per site, with the measured evidence behind every recommendation.

Author: PizzyLee

The Problem

Heat is the deadliest weather hazard for outdoor workers, and the crews who face it most (small construction, landscaping, and maintenance teams) are the least likely to have safety analysts or climate tooling. Supervisors schedule work by city-wide forecasts that can't see street-level reality, so strenuous tasks routinely land in the hottest hours of the hottest places.

The Solution

A supervisor selects 2–3 job sites in a US city. HeatShift:

1. Detects the most recent days available in FortyGuard's archive automatically
2. Builds each site's typical hour-by-hour heat curve from measured 2 m data
3. Classifies every hour (Low / Moderate / High / Extreme)
4. Ranks work windows coolest→hottest per site and across all sites
5. Shows the evidence: real measured min/mean/max behind each rating

Output example: "Best window across all sites: 06:00–07:00 at Downtown asphalt core (30.7°C)", plus which sites run hotter than others at that hour.

Honest Data Story

HeatShift deliberately runs on measured archive intelligence, not forecasts:

• During development we found that future-hour requests completed but returned empty tile sets, and that recent-day availability lags several days.
• FortyGuard staff later confirmed forecast-endpoint instability in the event Slack (Aug 20).
• We had already architected around it: adaptive date probing finds whatever the archive reliably serves, multi-day medians smooth noise, empty or partial days degrade gracefully instead of crashing the experience.

Resilience was not an afterthought; it is the design.

Architecture

Browser (Next.js UI, Leaflet map)
   |  click pins -> POST /api/fortyguard
   v
Vercel serverless route  <- FORTYGUARD_API_KEY (server-only secret)
   |  submit N async jobs (site x hour), poll /v1/status/{id}
   v
FortyGuard Temperature API (heatmap archive)
   |  NDJSON stream back per completed hour
   v
Engine (pure TS): median curves -> bands -> ranked windows

• Streaming: results render hour-by-hour as jobs complete (NDJSON)
• Precomputed demo mode: the flagship Phoenix scenario ships as committed JSON generated by scripts/warm-demo.ts, so judges get instant, reliable results, with one-click "Refresh live" for the real-time API path
• Graceful degradation: unavailable dates are probed and skipped; partial days are labeled, never hidden

FortyGuard API Usage

• POST /v1/heatmap: one closed ~500 m GeoJSON polygon per site, filter_type=1 per hour (06:00–18:00), granularity: 100
• GET /v1/status/{activity_id}: bounded polling (3–5 s interval), transient-404 retries, 429 exponential backoff
• Tile average_temperature properties aggregated via median across days
• Credits charged only on Completed tasks; empty responses treated as "date unavailable"

Tech Stack

Next.js (App Router) · TypeScript strict · Tailwind CSS · react-leaflet · Vitest · Vercel

Run Locally

git clone https://github.com/Pizzylee001/heatshift.git
cd heatshift
npm install
echo "FORTYGUARD_API_KEY=your_key" > .env.local
npm run dev

Disclaimer

HeatShift provides planning guidance derived from measured temperature data. It is not a medical or occupational-safety rating; always follow official workplace heat-safety requirements.

---