yogananthj/micro-heat-alert

Purpose and Scope

HeatSafe Guide is a single-page heat-risk dashboard for a fixed city/neighborhood. It visualizes hyperlocal temperature variation on an interactive map and turns map conditions plus a selected outdoor activity into plain-language safety recommendations. The intended integrations are FortyGuard Temperature APIs and an LLM-backed recommendation service; the app can use isolated/mock data when those services are unavailable.

Application Entry and Runtime

The client starts through the TypeScript application bootstrap in src/start.ts, with server/runtime handling in src/server.ts. Routing is configured in src/router.tsx and generated route definitions in src/routeTree.gen.ts. This is a Vite-based React/TypeScript application, with Bun artifacts/configuration also present (bun.lock, bunfig.toml).

Route and Page Composition

The root route establishes shared application structure in src/routes/__root.tsx; the primary dashboard is the index route at src/routes/index.tsx. The dashboard owns user-facing control flow: activity selection and time changes drive the displayed heat data and recommendation state. Styling is centralized in src/styles.css.

Heatmap Data Boundary

src/lib/heatmap.ts is the key data-access boundary for heatmap/grid data. It should encapsulate live FortyGuard calls, async-job polling where necessary, and the mock fallback described by the project scope. UI components should consume normalized grid/cell data rather than API-specific response shapes, keeping API-key handling and vendor response changes out of browser presentation code.

Map Visualization and Interaction

src/components/HeatLeafletMap.tsx renders the geographic heat overlay using Leaflet and map tiles. It receives heat cells for the selected forecast time, maps temperatures to risk colors, and is the natural boundary for tile/cell selection. A selected location can trigger point-level contextual detail (surface, shade, vegetation) through the data/service layer rather than calling FortyGuard directly from the map component.

Recommendation Pipeline

src/components/RecommendationPanel.tsx presents the AI-produced risk summary, safer time window, and zones to avoid. Recommendation prompt construction and the request contract reside in src/lib/recommend-prompt.ts and src/lib/recommend.functions.ts. The input flow is: selected activity + selected time + normalized heatmap/forecast data (+ optional point context) → structured LLM prompt → strict structured recommendation response → panel rendering.

Server-Side External-Service Boundary

The server layer in src/server.ts should protect secrets and proxy external API calls. Its material external dependencies are FortyGuard’s heatmap and point-report APIs, Anthropic/Claude for reasoning, and Leaflet/OpenStreetMap for client map rendering. No persistent database is indicated; short-lived in-memory caching is appropriate for heatmap jobs and repeated recommendation requests.

Reliability and UI Foundation

Error capture/reporting is separated under src/lib/error-capture.ts, src/lib/error-page.ts, and src/lib/lovable-error-reporting.ts, supporting resilient loading/error states around vendor API latency or failures. Reusable UI primitives live in src/components/ui, while the architecture-defining feature components remain src/components/HeatLeafletMap.tsx and src/components/RecommendationPanel.tsx.