# astrotemporal/firepoint architecture

> Architecture diagram of the GitHub repository astrotemporal/firepoint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astrotemporal/firepoint
- Repository: https://github.com/astrotemporal/firepoint

## Overview

Firepoint is a mobile-first wildfire preparedness and evacuation web app for Glendale. Residents use the map to set a private fire mark, share their location or choose a starting point, and request a fire-aware shelter route or an escape route; a separate Ready, Set, Go guide supports preparation. The graph also includes the documented language and offline capabilities and the live hazard/context API branch. Some components are included based on the README and source index rather than inspected implementation; edges are limited to documented or indexed relationships.

Main entry points: [`src/components/map-screen.tsx`](https://github.com/astrotemporal/firepoint/blob/main/src/components/map-screen.tsx) (Map Screen), [`src/app/api/v1/context/query/route.ts`](https://github.com/astrotemporal/firepoint/blob/main/src/app/api/v1/context/query/route.ts) (Fire & Air Context API), [`src/evacuation/route-planner.ts`](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/route-planner.ts) (Route Planner), [`src/components/route-bar.tsx`](https://github.com/astrotemporal/firepoint/blob/main/src/components/route-bar.tsx) (Route Controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_evacuation["Map &amp; Evacuation"]
  node_map_page["Map Page<br/>[page.tsx]"]
  node_map_screen["Map Screen<br/>[map-screen.tsx]"]
  node_map_view["Evacuation Map<br/>[evacuation-map.tsx]"]
  node_route_controls["Route Controls<br/>[route-bar.tsx]"]
  node_navigation["Turn-by-turn Navigation<br/>[navigation.ts]"]
  node_fire_marks["Private Fire Marks<br/>[fire-marks.ts]"]
end

subgraph group_routing["Routing Engine"]
  node_location["Location Handling<br/>[location.ts]"]
  node_route_planner["Route Planner<br/>[route-planner.ts]"]
  node_shelter_routing["Shelter Routing<br/>[routing.ts]"]
  node_escape_routing["Escape Routing<br/>[escape.ts]"]
  node_route_provider["Route Provider<br/>[route-provider.ts]"]
  node_shelter_data["Glendale Shelter Data<br/>[glendale.ts]"]
  node_wildland["Wildland Hazard Data<br/>[wildland.ts]"]
end

subgraph group_information["Guidance &amp; Language"]
  node_prepare_page["Preparation Page<br/>[page.tsx]"]
  node_guide["Wildfire Guide<br/>[wildfire-guide.tsx]"]
  node_guide_content["Guide Content<br/>[wildfire-guide.ts]"]
  node_locales["Language Negotiation<br/>[locales.ts]"]
  node_map_translations["Map Translations<br/>[map.ts]"]
end

subgraph group_live["Live Information APIs"]
  node_context_api["Fire &amp; Air Context API<br/>[route.ts]"]
  node_context_feed["Context Feed<br/>[context-feed.ts]"]
  node_place_query["Place Query Validation<br/>[place-query.ts]"]
  node_source_gate["Live Source Gate<br/>[live-query-gate.ts]"]
  node_calfire["CAL FIRE Adapter<br/>[calfire.ts]"]
  node_nifc["NIFC Adapter<br/>[nifc.ts]"]
  node_airnow["AirNow Adapter<br/>[airnow.ts]"]
  node_hazards_api["Hazards API<br/>[route.ts]"]
  node_notices_api["Notices API<br/>[route.ts]"]
end

subgraph group_platform["Offline Platform"]
  node_offline_registration["Service Worker Registration<br/>[service-worker.ts]"]
  node_service_worker["Offline Worker<br/>[sw.js]"]
end

node_resident(("Resident"))

node_resident -->|"opens map"| node_map_page
node_map_page -->|"renders"| node_map_screen
node_map_screen -->|"renders"| node_map_view
node_map_screen -->|"renders"| node_route_controls
node_map_screen -->|"uses"| node_fire_marks
node_map_screen -->|"uses"| node_location
node_map_screen -->|"requests plans"| node_route_planner
node_map_screen -->|"loads"| node_shelter_data
node_map_screen -->|"loads"| node_wildland
node_route_controls -->|"requests routes"| node_route_planner
node_route_controls -->|"uses"| node_location
node_route_controls -->|"uses"| node_map_translations
node_route_planner -->|"uses"| node_shelter_routing
node_route_planner -->|"uses"| node_escape_routing
node_route_planner -->|"uses"| node_wildland
node_route_planner -.->|"uses"| node_route_provider
node_map_screen -.->|"supports"| node_navigation
node_resident -->|"opens guide"| node_prepare_page
node_prepare_page -->|"renders"| node_guide
node_prepare_page -->|"loads"| node_guide_content
node_prepare_page -->|"gets language"| node_locales
node_map_page -->|"gets language"| node_locales
node_context_api -->|"validates query"| node_place_query
node_context_api -->|"checks access"| node_source_gate
node_context_api -->|"fetches incidents"| node_calfire
node_context_api -->|"fetches perimeters"| node_nifc
node_context_api -->|"fetches observations"| node_airnow
node_context_api -->|"builds feed"| node_context_feed
node_hazards_api -->|"validates query"| node_place_query
node_hazards_api -->|"checks access"| node_source_gate
node_notices_api -->|"validates query"| node_place_query
node_notices_api -->|"checks access"| node_source_gate
node_resident -.->|"uses offline app"| node_offline_registration
node_offline_registration -->|"registers"| node_service_worker

click node_map_page "https://github.com/astrotemporal/firepoint/blob/main/src/app/page.tsx"
click node_map_screen "https://github.com/astrotemporal/firepoint/blob/main/src/components/map-screen.tsx"
click node_map_view "https://github.com/astrotemporal/firepoint/blob/main/src/components/evacuation-map.tsx"
click node_route_controls "https://github.com/astrotemporal/firepoint/blob/main/src/components/route-bar.tsx"
click node_navigation "https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/navigation.ts"
click node_fire_marks "https://github.com/astrotemporal/firepoint/blob/main/src/domain/fire-marks.ts"
click node_location "https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/location.ts"
click node_route_planner "https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/route-planner.ts"
click node_shelter_routing "https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/routing.ts"
click node_escape_routing "https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/escape.ts"
click node_route_provider "https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/route-provider.ts"
click node_shelter_data "https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/data/glendale.ts"
click node_wildland "https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/data/wildland.ts"
click node_prepare_page "https://github.com/astrotemporal/firepoint/blob/main/src/app/prepare/page.tsx"
click node_guide "https://github.com/astrotemporal/firepoint/blob/main/src/components/wildfire-guide.tsx"
click node_guide_content "https://github.com/astrotemporal/firepoint/blob/main/src/domain/wildfire-guide.ts"
click node_locales "https://github.com/astrotemporal/firepoint/blob/main/src/i18n/locales.ts"
click node_map_translations "https://github.com/astrotemporal/firepoint/blob/main/src/i18n/map.ts"
click node_context_api "https://github.com/astrotemporal/firepoint/blob/main/src/app/api/v1/context/query/route.ts"
click node_context_feed "https://github.com/astrotemporal/firepoint/blob/main/src/domain/context-feed.ts"
click node_place_query "https://github.com/astrotemporal/firepoint/blob/main/src/server/place-query.ts"
click node_source_gate "https://github.com/astrotemporal/firepoint/blob/main/src/server/live-query-gate.ts"
click node_calfire "https://github.com/astrotemporal/firepoint/blob/main/src/server/calfire.ts"
click node_nifc "https://github.com/astrotemporal/firepoint/blob/main/src/server/nifc.ts"
click node_airnow "https://github.com/astrotemporal/firepoint/blob/main/src/server/airnow.ts"
click node_hazards_api "https://github.com/astrotemporal/firepoint/blob/main/src/app/api/v1/hazards/query/route.ts"
click node_notices_api "https://github.com/astrotemporal/firepoint/blob/main/src/app/api/v1/notices/query/route.ts"
click node_offline_registration "https://github.com/astrotemporal/firepoint/blob/main/src/lib/service-worker.ts"
click node_service_worker "https://github.com/astrotemporal/firepoint/blob/main/public/sw.js"

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_map_page,node_map_screen,node_map_view,node_route_controls,node_navigation,node_fire_marks toneBlue
class node_location,node_route_planner,node_shelter_routing,node_escape_routing,node_route_provider,node_shelter_data,node_wildland toneAmber
class node_prepare_page,node_guide,node_guide_content,node_locales,node_map_translations toneMint
class node_context_api,node_context_feed,node_place_query,node_source_gate,node_calfire,node_nifc,node_airnow,node_hazards_api,node_notices_api toneRose
class node_offline_registration,node_service_worker,node_resident toneIndigo
```

## Components

### Map & Evacuation

- [Map Page](https://github.com/astrotemporal/firepoint/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Map Screen](https://github.com/astrotemporal/firepoint/blob/main/src/components/map-screen.tsx): `src/components/map-screen.tsx`
- [Evacuation Map](https://github.com/astrotemporal/firepoint/blob/main/src/components/evacuation-map.tsx): `src/components/evacuation-map.tsx`
- [Route Controls](https://github.com/astrotemporal/firepoint/blob/main/src/components/route-bar.tsx): `src/components/route-bar.tsx`
- [Turn-by-turn Navigation](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/navigation.ts): `src/evacuation/navigation.ts`
- [Private Fire Marks](https://github.com/astrotemporal/firepoint/blob/main/src/domain/fire-marks.ts): `src/domain/fire-marks.ts`

### Routing Engine

- [Location Handling](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/location.ts): `src/evacuation/location.ts`
- [Route Planner](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/route-planner.ts): `src/evacuation/route-planner.ts`
- [Shelter Routing](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/routing.ts): `src/evacuation/routing.ts`
- [Escape Routing](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/escape.ts): `src/evacuation/escape.ts`
- [Route Provider](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/route-provider.ts): `src/evacuation/route-provider.ts`
- [Glendale Shelter Data](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/data/glendale.ts): `src/evacuation/data/glendale.ts`
- [Wildland Hazard Data](https://github.com/astrotemporal/firepoint/blob/main/src/evacuation/data/wildland.ts): `src/evacuation/data/wildland.ts`

### Guidance & Language

- [Preparation Page](https://github.com/astrotemporal/firepoint/blob/main/src/app/prepare/page.tsx): `src/app/prepare/page.tsx`
- [Wildfire Guide](https://github.com/astrotemporal/firepoint/blob/main/src/components/wildfire-guide.tsx): `src/components/wildfire-guide.tsx`
- [Guide Content](https://github.com/astrotemporal/firepoint/blob/main/src/domain/wildfire-guide.ts): `src/domain/wildfire-guide.ts`
- [Language Negotiation](https://github.com/astrotemporal/firepoint/blob/main/src/i18n/locales.ts): `src/i18n/locales.ts`
- [Map Translations](https://github.com/astrotemporal/firepoint/blob/main/src/i18n/map.ts): `src/i18n/map.ts`

### Live Information APIs

- [Fire & Air Context API](https://github.com/astrotemporal/firepoint/blob/main/src/app/api/v1/context/query/route.ts): `src/app/api/v1/context/query/route.ts`
- [Context Feed](https://github.com/astrotemporal/firepoint/blob/main/src/domain/context-feed.ts): `src/domain/context-feed.ts`
- [Place Query Validation](https://github.com/astrotemporal/firepoint/blob/main/src/server/place-query.ts): `src/server/place-query.ts`
- [Live Source Gate](https://github.com/astrotemporal/firepoint/blob/main/src/server/live-query-gate.ts): `src/server/live-query-gate.ts`
- [CAL FIRE Adapter](https://github.com/astrotemporal/firepoint/blob/main/src/server/calfire.ts): `src/server/calfire.ts`
- [NIFC Adapter](https://github.com/astrotemporal/firepoint/blob/main/src/server/nifc.ts): `src/server/nifc.ts`
- [AirNow Adapter](https://github.com/astrotemporal/firepoint/blob/main/src/server/airnow.ts): `src/server/airnow.ts`
- [Hazards API](https://github.com/astrotemporal/firepoint/blob/main/src/app/api/v1/hazards/query/route.ts): `src/app/api/v1/hazards/query/route.ts`
- [Notices API](https://github.com/astrotemporal/firepoint/blob/main/src/app/api/v1/notices/query/route.ts): `src/app/api/v1/notices/query/route.ts`

### Offline Platform

- [Service Worker Registration](https://github.com/astrotemporal/firepoint/blob/main/src/lib/service-worker.ts): `src/lib/service-worker.ts`
- [Offline Worker](https://github.com/astrotemporal/firepoint/blob/main/public/sw.js): `public/sw.js`

### Other components

- **Resident**

## Connections

- Resident → Map Page: opens map (evidence: `README.md`)
- Map Page → Map Screen: renders (evidence: `src/app/page.tsx`)
- Map Screen → Evacuation Map: renders (evidence: `src/components/map-screen.tsx`)
- Map Screen → Route Controls: renders (evidence: `src/components/map-screen.tsx`)
- Map Screen → Private Fire Marks: uses (evidence: `src/components/map-screen.tsx`)
- Map Screen → Location Handling: uses (evidence: `src/components/map-screen.tsx`)
- Map Screen → Route Planner: requests plans (evidence: `src/components/map-screen.tsx`)
- Map Screen → Glendale Shelter Data: loads (evidence: `src/components/map-screen.tsx`)
- Map Screen → Wildland Hazard Data: loads (evidence: `src/components/map-screen.tsx`)
- Route Controls → Route Planner: requests routes (evidence: `src/components/route-bar.tsx`)
- Route Controls → Location Handling: uses (evidence: `src/components/route-bar.tsx`)
- Route Controls → Map Translations: uses (evidence: `src/components/route-bar.tsx`)
- Route Planner → Shelter Routing: uses (evidence: `src/evacuation/route-planner.ts`)
- Route Planner → Escape Routing: uses (evidence: `src/evacuation/route-planner.ts`)
- Route Planner → Wildland Hazard Data: uses (evidence: `src/evacuation/route-planner.ts`)
- Route Planner → Route Provider: uses
- Map Screen → Turn-by-turn Navigation: supports (evidence: `src/components/map-screen.tsx`)
- Resident → Preparation Page: opens guide (evidence: `README.md`)
- Preparation Page → Wildfire Guide: renders (evidence: `src/app/prepare/page.tsx`)
- Preparation Page → Guide Content: loads (evidence: `src/app/prepare/page.tsx`)
- Preparation Page → Language Negotiation: gets language (evidence: `src/app/prepare/page.tsx`)
- Map Page → Language Negotiation: gets language (evidence: `src/app/page.tsx`)
- Fire & Air Context API → Place Query Validation: validates query (evidence: `src/app/api/v1/context/query/route.ts`)
- Fire & Air Context API → Live Source Gate: checks access (evidence: `src/app/api/v1/context/query/route.ts`)
- Fire & Air Context API → CAL FIRE Adapter: fetches incidents (evidence: `src/app/api/v1/context/query/route.ts`)
- Fire & Air Context API → NIFC Adapter: fetches perimeters (evidence: `src/app/api/v1/context/query/route.ts`)
- Fire & Air Context API → AirNow Adapter: fetches observations (evidence: `src/app/api/v1/context/query/route.ts`)
- Fire & Air Context API → Context Feed: builds feed (evidence: `src/app/api/v1/context/query/route.ts`)
- Hazards API → Place Query Validation: validates query (evidence: `src/app/api/v1/hazards/query/route.ts`)
- Hazards API → Live Source Gate: checks access (evidence: `src/app/api/v1/hazards/query/route.ts`)
- Notices API → Place Query Validation: validates query (evidence: `src/app/api/v1/notices/query/route.ts`)
- Notices API → Live Source Gate: checks access (evidence: `src/app/api/v1/notices/query/route.ts`)
- Resident → Service Worker Registration: uses offline app (evidence: `README.md`)
- Service Worker Registration → Offline Worker: registers (evidence: `src/lib/service-worker.ts`)
