# robro1236/kestrel architecture

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

- Interactive diagram: https://gitdiagram.com/robro1236/kestrel
- Repository: https://github.com/robro1236/kestrel

## Overview

Kestrel is a phone-first disaster preparedness app that turns a household’s location and membership into a personalized emergency plan. The main workflow is welcome → household and location setup → plan generation and live local information; users then manage kit progress and open specialized now, hazards, water, nearby-help, and family-card views. The README documents these capabilities, while the excerpts show local persistence, area refresh, nearby-places lookup, and kit rules. Several screen and data-source details are unsampled, so their documented connections are shown without implying unverified internal calls.

Main entry points: [`app/plan.tsx`](https://github.com/robro1236/kestrel/blob/main/app/plan.tsx) (Emergency plan), [`src/storage.ts`](https://github.com/robro1236/kestrel/blob/main/src/storage.ts) (On-device storage), [`app/index.tsx`](https://github.com/robro1236/kestrel/blob/main/app/index.tsx) (Welcome), [`src/useLocalArea.ts`](https://github.com/robro1236/kestrel/blob/main/src/useLocalArea.ts) (Local area state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onboarding["Onboarding and plan"]
  node_welcome["Welcome<br/>[index.tsx]"]
  node_setup["Household setup<br/>[setup.tsx]"]
  node_plan["Emergency plan<br/>[plan.tsx]"]
  node_rules["Kit rules<br/>[rules.ts]"]
end

subgraph group_preparedness["Preparedness tools"]
  node_now["Now guidance<br/>[now.tsx]"]
  node_hazards["Hazard guidance<br/>[hazards.tsx]"]
  node_water["Water safety<br/>[water.tsx]"]
  node_help["Nearby help<br/>[NearbyHelp.tsx]"]
  node_family["Family plan card<br/>[family.tsx]"]
  node_history["Risk history<br/>[history.tsx]"]
end

subgraph group_localdata["Local information"]
  node_localarea["Local area state<br/>[useLocalArea.ts]"]
  node_location["Location lookup<br/>[location.ts]"]
  node_fema["Hazard risk data<br/>[fema.ts]"]
  node_nws["Weather warnings<br/>[nws.ts]"]
  node_air["Air quality<br/>[airQuality.ts]"]
  node_waterdata["Water system data<br/>[waterSystem.ts]"]
  node_lookup["Area lookup API<br/>[handler.ts]"]
  node_places["Nearby places<br/>[places.ts]"]
end

subgraph group_platform["App services"]
  node_storage[("On-device storage<br/>[storage.ts]")]
  node_supabase["Supabase client<br/>[supabase.ts]"]
end

node_resident(("Household"))
node_publicsources["Public information sources"]

node_resident -->|"opens app"| node_welcome
node_welcome -->|"starts plan"| node_setup
node_setup -.->|"saves answers"| node_storage
node_welcome -->|"checks saved plan"| node_storage
node_plan -.->|"loads progress"| node_storage
node_plan -.->|"builds kit"| node_rules
node_plan -->|"loads local data"| node_localarea
node_localarea -->|"reads cached results"| node_storage
node_localarea -->|"refreshes area"| node_supabase
node_supabase -.->|"requests lookup"| node_lookup
node_help -->|"requests places"| node_lookup
node_lookup -.->|"dispatches places"| node_places
node_plan -.->|"shows warnings"| node_nws
node_plan -->|"shows air alerts"| node_air
node_plan -.->|"shows water status"| node_waterdata
node_plan -.->|"shows area hazards"| node_fema
node_resident -->|"opens urgent guidance"| node_now
node_resident -->|"reviews hazards"| node_hazards
node_resident -->|"checks water safety"| node_water
node_resident -->|"finds local help"| node_help
node_resident -->|"opens family card"| node_family
node_resident -->|"reviews risk history"| node_history
node_publicsources -.->|"provides risk data"| node_fema
node_publicsources -.->|"provides warnings"| node_nws
node_publicsources -.->|"provides air data"| node_air
node_publicsources -.->|"provides water data"| node_waterdata

click node_welcome "https://github.com/robro1236/kestrel/blob/main/app/index.tsx"
click node_setup "https://github.com/robro1236/kestrel/blob/main/app/setup.tsx"
click node_plan "https://github.com/robro1236/kestrel/blob/main/app/plan.tsx"
click node_rules "https://github.com/robro1236/kestrel/blob/main/src/kit/rules.ts"
click node_localarea "https://github.com/robro1236/kestrel/blob/main/src/useLocalArea.ts"
click node_location "https://github.com/robro1236/kestrel/blob/main/src/data/location.ts"
click node_fema "https://github.com/robro1236/kestrel/blob/main/src/data/fema.ts"
click node_nws "https://github.com/robro1236/kestrel/blob/main/src/data/nws.ts"
click node_air "https://github.com/robro1236/kestrel/blob/main/src/data/airQuality.ts"
click node_waterdata "https://github.com/robro1236/kestrel/blob/main/src/data/waterSystem.ts"
click node_lookup "https://github.com/robro1236/kestrel/blob/main/supabase/functions/lookup/handler.ts"
click node_places "https://github.com/robro1236/kestrel/blob/main/supabase/functions/lookup/places.ts"
click node_now "https://github.com/robro1236/kestrel/blob/main/app/now.tsx"
click node_hazards "https://github.com/robro1236/kestrel/blob/main/app/hazards.tsx"
click node_water "https://github.com/robro1236/kestrel/blob/main/app/water.tsx"
click node_help "https://github.com/robro1236/kestrel/blob/main/src/components/NearbyHelp.tsx"
click node_family "https://github.com/robro1236/kestrel/blob/main/app/family.tsx"
click node_history "https://github.com/robro1236/kestrel/blob/main/app/history.tsx"
click node_storage "https://github.com/robro1236/kestrel/blob/main/src/storage.ts"
click node_supabase "https://github.com/robro1236/kestrel/blob/main/src/supabase.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_welcome,node_setup,node_plan,node_rules toneBlue
class node_now,node_hazards,node_water,node_help,node_family,node_history toneAmber
class node_localarea,node_location,node_fema,node_nws,node_air,node_waterdata,node_lookup,node_places toneMint
class node_storage,node_supabase toneRose
class node_resident,node_publicsources toneIndigo
```

## Components

### Onboarding and plan

- [Welcome](https://github.com/robro1236/kestrel/blob/main/app/index.tsx): `app/index.tsx`
- [Household setup](https://github.com/robro1236/kestrel/blob/main/app/setup.tsx): `app/setup.tsx`
- [Emergency plan](https://github.com/robro1236/kestrel/blob/main/app/plan.tsx): `app/plan.tsx`
- [Kit rules](https://github.com/robro1236/kestrel/blob/main/src/kit/rules.ts): `src/kit/rules.ts`

### Preparedness tools

- [Now guidance](https://github.com/robro1236/kestrel/blob/main/app/now.tsx): `app/now.tsx`
- [Hazard guidance](https://github.com/robro1236/kestrel/blob/main/app/hazards.tsx): `app/hazards.tsx`
- [Water safety](https://github.com/robro1236/kestrel/blob/main/app/water.tsx): `app/water.tsx`
- [Nearby help](https://github.com/robro1236/kestrel/blob/main/src/components/NearbyHelp.tsx): `src/components/NearbyHelp.tsx`
- [Family plan card](https://github.com/robro1236/kestrel/blob/main/app/family.tsx): `app/family.tsx`
- [Risk history](https://github.com/robro1236/kestrel/blob/main/app/history.tsx): `app/history.tsx`

### Local information

- [Local area state](https://github.com/robro1236/kestrel/blob/main/src/useLocalArea.ts): `src/useLocalArea.ts`
- [Location lookup](https://github.com/robro1236/kestrel/blob/main/src/data/location.ts): `src/data/location.ts`
- [Hazard risk data](https://github.com/robro1236/kestrel/blob/main/src/data/fema.ts): `src/data/fema.ts`
- [Weather warnings](https://github.com/robro1236/kestrel/blob/main/src/data/nws.ts): `src/data/nws.ts`
- [Air quality](https://github.com/robro1236/kestrel/blob/main/src/data/airQuality.ts): `src/data/airQuality.ts`
- [Water system data](https://github.com/robro1236/kestrel/blob/main/src/data/waterSystem.ts): `src/data/waterSystem.ts`
- [Area lookup API](https://github.com/robro1236/kestrel/blob/main/supabase/functions/lookup/handler.ts): `supabase/functions/lookup/handler.ts`
- [Nearby places](https://github.com/robro1236/kestrel/blob/main/supabase/functions/lookup/places.ts): `supabase/functions/lookup/places.ts`

### App services

- [On-device storage](https://github.com/robro1236/kestrel/blob/main/src/storage.ts): `src/storage.ts`
- [Supabase client](https://github.com/robro1236/kestrel/blob/main/src/supabase.ts): `src/supabase.ts`

### Other components

- **Household**
- **Public information sources**

## Connections

- Household → Welcome: opens app (evidence: `README.md`)
- Welcome → Household setup: starts plan (evidence: `app/index.tsx`)
- Household setup → On-device storage: saves answers
- Welcome → On-device storage: checks saved plan (evidence: `app/index.tsx`)
- Emergency plan → On-device storage: loads progress (evidence: `app/plan.tsx`)
- Emergency plan → Kit rules: builds kit (evidence: `app/plan.tsx`)
- Emergency plan → Local area state: loads local data (evidence: `src/useLocalArea.ts`)
- Local area state → On-device storage: reads cached results (evidence: `src/useLocalArea.ts`)
- Local area state → Supabase client: refreshes area (evidence: `src/useLocalArea.ts`)
- Supabase client → Area lookup API: requests lookup
- Nearby help → Area lookup API: requests places (evidence: `src/components/NearbyHelp.tsx`)
- Area lookup API → Nearby places: dispatches places
- Emergency plan → Weather warnings: shows warnings (evidence: `app/plan.tsx`)
- Emergency plan → Air quality: shows air alerts (evidence: `app/plan.tsx`)
- Emergency plan → Water system data: shows water status
- Emergency plan → Hazard risk data: shows area hazards
- Household → Now guidance: opens urgent guidance (evidence: `README.md`)
- Household → Hazard guidance: reviews hazards (evidence: `README.md`)
- Household → Water safety: checks water safety (evidence: `README.md`)
- Household → Nearby help: finds local help (evidence: `README.md`)
- Household → Family plan card: opens family card (evidence: `README.md`)
- Household → Risk history: reviews risk history (evidence: `README.md`)
- Public information sources → Hazard risk data: provides risk data (evidence: `README.md`)
- Public information sources → Weather warnings: provides warnings (evidence: `README.md`)
- Public information sources → Air quality: provides air data (evidence: `README.md`)
- Public information sources → Water system data: provides water data (evidence: `README.md`)
