# yogananthj/micro-heat-alert architecture

> Architecture diagram of the GitHub repository yogananthj/micro-heat-alert, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yogananthj/micro-heat-alert
- Repository: https://github.com/yogananthj/micro-heat-alert

## Overview

#### 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`.

Main entry points: [`src/routes/index.tsx`](https://github.com/yogananthj/micro-heat-alert/blob/main/src/routes/index.tsx) (Heat-risk dashboard), [`src/server.ts`](https://github.com/yogananthj/micro-heat-alert/blob/main/src/server.ts) (Server runtime), [`src/router.tsx`](https://github.com/yogananthj/micro-heat-alert/blob/main/src/router.tsx) (Router and route tree), [`src/routes/__root.tsx`](https://github.com/yogananthj/micro-heat-alert/blob/main/src/routes/__root.tsx) (Root application shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React dashboard"]
  node_bootstrap["Application bootstrap<br/>TypeScript entry<br/>[start.ts]"]
  node_router["Router and route tree<br/>routing<br/>[router.tsx]"]
  node_route_tree["Generated route tree<br/>generated routes<br/>[routeTree.gen.ts]"]
  node_root_route["Root application shell<br/>root route<br/>[__root.tsx]"]
  node_dashboard["Heat-risk dashboard<br/>index route<br/>[index.tsx]"]
  node_map["Interactive heat map<br/>feature component<br/>[HeatLeafletMap.tsx]"]
  node_recommendation_panel["Recommendation panel<br/>feature component"]
  node_ui_primitives["Reusable UI primitives<br/>component library"]
  node_styles["Application styles<br/>stylesheet<br/>[styles.css]"]
end

subgraph group_data["Data and recommendation layer"]
  node_heatmap_boundary["Heatmap data boundary<br/>data access<br/>[heatmap.ts]"]
  node_recommend_prompt["Recommendation prompt<br/>prompt builder"]
  node_recommend_contract["Recommendation contract<br/>request contract"]
  node_error_handling["Error reporting and states<br/>reliability layer<br/>[error-capture.ts]"]
end

subgraph group_server["Server boundary"]
  node_server_runtime["Server runtime<br/>server entry<br/>[server.ts]"]
end

subgraph group_external["External services"]
  node_fortyguard{{"FortyGuard APIs<br/>heat data provider"}}
  node_anthropic{{"Anthropic Claude<br/>LLM provider"}}
  node_leaflet_osm{{"Leaflet and OSM tiles<br/>map rendering provider"}}
end

node_bootstrap -->|"starts runtime"| node_server_runtime
node_bootstrap -->|"mounts app"| node_router
node_router -->|"uses definitions"| node_route_tree
node_router -->|"resolves root"| node_root_route
node_root_route -->|"renders"| node_dashboard
node_dashboard -->|"selected time and cells"| node_map
node_dashboard -->|"activity and recommendation"| node_recommendation_panel
node_dashboard -->|"requests normalized heat data"| node_heatmap_boundary
node_map -->|"requests point context"| node_heatmap_boundary
node_map -->|"renders overlay and tiles"| node_leaflet_osm
node_heatmap_boundary -->|"proxies data requests"| node_server_runtime
node_server_runtime -->|"heatmap and point reports"| node_fortyguard
node_dashboard -->|"activity, time, heat context"| node_recommend_prompt
node_recommend_prompt -->|"structured request"| node_recommend_contract
node_recommend_contract -->|"recommendation request"| node_server_runtime
node_server_runtime -->|"reasoning request"| node_anthropic
node_recommend_contract -->|"structured response"| node_recommendation_panel
node_dashboard -.->|"loading and failure states"| node_error_handling
node_root_route -->|"applies"| node_styles
node_dashboard -->|"composes"| node_ui_primitives

click node_bootstrap "https://github.com/yogananthj/micro-heat-alert/blob/main/src/start.ts"
click node_server_runtime "https://github.com/yogananthj/micro-heat-alert/blob/main/src/server.ts"
click node_router "https://github.com/yogananthj/micro-heat-alert/blob/main/src/router.tsx"
click node_route_tree "https://github.com/yogananthj/micro-heat-alert/blob/main/src/routeTree.gen.ts"
click node_root_route "https://github.com/yogananthj/micro-heat-alert/blob/main/src/routes/__root.tsx"
click node_dashboard "https://github.com/yogananthj/micro-heat-alert/blob/main/src/routes/index.tsx"
click node_map "https://github.com/yogananthj/micro-heat-alert/blob/main/src/components/HeatLeafletMap.tsx"
click node_recommendation_panel "https://github.com/yogananthj/micro-heat-alert/blob/main/src/components/RecommendationPanel.tsx"
click node_ui_primitives "https://github.com/yogananthj/micro-heat-alert/tree/main/src/components/ui"
click node_styles "https://github.com/yogananthj/micro-heat-alert/blob/main/src/styles.css"
click node_heatmap_boundary "https://github.com/yogananthj/micro-heat-alert/blob/main/src/lib/heatmap.ts"
click node_recommend_prompt "https://github.com/yogananthj/micro-heat-alert/blob/main/src/lib/recommend-prompt.ts"
click node_recommend_contract "https://github.com/yogananthj/micro-heat-alert/blob/main/src/lib/recommend.functions.ts"
click node_error_handling "https://github.com/yogananthj/micro-heat-alert/blob/main/src/lib/error-capture.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_router,node_route_tree,node_root_route,node_dashboard,node_map,node_recommendation_panel,node_ui_primitives,node_styles toneBlue
class node_heatmap_boundary,node_recommend_prompt,node_recommend_contract,node_error_handling toneAmber
class node_server_runtime toneMint
class node_fortyguard,node_anthropic,node_leaflet_osm toneRose
```

## Components

### React dashboard

Browser UI and feature composition.

- [Application bootstrap](https://github.com/yogananthj/micro-heat-alert/blob/main/src/start.ts): TypeScript entry · `src/start.ts`
- [Router and route tree](https://github.com/yogananthj/micro-heat-alert/blob/main/src/router.tsx): routing · `src/router.tsx`
- [Generated route tree](https://github.com/yogananthj/micro-heat-alert/blob/main/src/routeTree.gen.ts): generated routes · `src/routeTree.gen.ts`
- [Root application shell](https://github.com/yogananthj/micro-heat-alert/blob/main/src/routes/__root.tsx): root route · `src/routes/__root.tsx`
- [Heat-risk dashboard](https://github.com/yogananthj/micro-heat-alert/blob/main/src/routes/index.tsx): index route · Coordinates activity, forecast time, heat data, and recommendations. · `src/routes/index.tsx`
- [Interactive heat map](https://github.com/yogananthj/micro-heat-alert/blob/main/src/components/HeatLeafletMap.tsx): feature component · Renders heat cells and location selection. · `src/components/HeatLeafletMap.tsx`
- [Recommendation panel](https://github.com/yogananthj/micro-heat-alert/blob/main/src/components/RecommendationPanel.tsx): feature component · Shows risk summary, safer window, and avoidance zones. · `src/components/RecommendationPanel.tsx`
- [Reusable UI primitives](https://github.com/yogananthj/micro-heat-alert/tree/main/src/components/ui): component library · `src/components/ui`
- [Application styles](https://github.com/yogananthj/micro-heat-alert/blob/main/src/styles.css): stylesheet · `src/styles.css`

### Data and recommendation layer

Normalized data contracts and reliability support.

- [Heatmap data boundary](https://github.com/yogananthj/micro-heat-alert/blob/main/src/lib/heatmap.ts): data access · Normalizes grids, polls jobs, and supplies mock fallback. · `src/lib/heatmap.ts`
- [Recommendation prompt](https://github.com/yogananthj/micro-heat-alert/blob/main/src/lib/recommend-prompt.ts): prompt builder · Builds structured LLM input from dashboard context. · `src/lib/recommend-prompt.ts`
- [Recommendation contract](https://github.com/yogananthj/micro-heat-alert/blob/main/src/lib/recommend.functions.ts): request contract · Defines strict structured recommendation exchange. · `src/lib/recommend.functions.ts`
- [Error reporting and states](https://github.com/yogananthj/micro-heat-alert/blob/main/src/lib/error-capture.ts): reliability layer · Captures failures and supports resilient error UI. · `src/lib/error-capture.ts`

### Server boundary

Secret-protected external-service proxy and cache.

- [Server runtime](https://github.com/yogananthj/micro-heat-alert/blob/main/src/server.ts): server entry · Proxies vendors and keeps short-lived caches. · `src/server.ts`

### External services

- **FortyGuard APIs**: heat data provider · Provides heatmaps, point reports, and async jobs.
- **Anthropic Claude**: LLM provider
- **Leaflet and OSM tiles**: map rendering provider

## Connections

- Application bootstrap → Server runtime: starts runtime
- Application bootstrap → Router and route tree: mounts app
- Router and route tree → Generated route tree: uses definitions
- Router and route tree → Root application shell: resolves root
- Root application shell → Heat-risk dashboard: renders
- Heat-risk dashboard → Interactive heat map: selected time and cells
- Heat-risk dashboard → Recommendation panel: activity and recommendation
- Heat-risk dashboard → Heatmap data boundary: requests normalized heat data
- Interactive heat map → Heatmap data boundary: requests point context
- Interactive heat map → Leaflet and OSM tiles: renders overlay and tiles
- Heatmap data boundary → Server runtime: proxies data requests
- Server runtime → FortyGuard APIs: heatmap and point reports
- Heat-risk dashboard → Recommendation prompt: activity, time, heat context
- Recommendation prompt → Recommendation contract: structured request
- Recommendation contract → Server runtime: recommendation request
- Server runtime → Anthropic Claude: reasoning request
- Recommendation contract → Recommendation panel: structured response
- Heat-risk dashboard → Error reporting and states: loading and failure states
- Root application shell → Application styles: applies
- Heat-risk dashboard → Reusable UI primitives: composes