# yuchirozen/safehub architecture

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

- Interactive diagram: https://gitdiagram.com/yuchirozen/safehub
- Repository: https://github.com/yuchirozen/safehub

## Overview

SAFEHUB is an emergency shelter and disaster-response platform spanning an ESP32 sensor node, an API gateway, Firebase services, and a role-based web app. The main user flow is: sign in, view live emergency conditions, find a suitable shelter or evacuation window, and request help; staff, helpers, medical volunteers, rescue teams, and administrators coordinate response through separate dashboards. The graph preserves major documented capabilities, including shelter management, alerts, hardware simulation, and facility discovery. Several page and backend implementations were not sampled, so those feature relationships rely on README documentation rather than inspected implementation.

Main entry points: [`src/App.tsx`](https://github.com/yuchirozen/safehub/blob/main/src/App.tsx) (App Router & Live State), [`server/index.ts`](https://github.com/yuchirozen/safehub/blob/main/server/index.ts) (Ingestion Gateway), [`src/pages/EmergencyHome.tsx`](https://github.com/yuchirozen/safehub/blob/main/src/pages/EmergencyHome.tsx) (Emergency Dashboard), [`src/pages/SheltersPage.tsx`](https://github.com/yuchirozen/safehub/blob/main/src/pages/SheltersPage.tsx) (Shelter Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Field Devices"]
  node_esp32["ESP32 Node"]
  node_simulator["Hardware Simulator"]
end

subgraph group_cloud["Cloud Services"]
  node_gateway["Ingestion Gateway<br/>[index.ts]"]
  node_firebase[("Firebase Auth &amp; Firestore")]
end

subgraph group_citizen["Evacuation &amp; Aid"]
  node_home["Emergency Dashboard<br/>[EmergencyHome.tsx]"]
  node_shelters["Shelter Discovery<br/>[SheltersPage.tsx]"]
  node_shelter_detail["Shelter Details"]
  node_suitability["Shelter Suitability<br/>[suitability.ts]"]
  node_evacuation["Evacuation Guidance"]
  node_evacuation_engine["Departure Window Engine<br/>[evacuation.ts]"]
  node_assistance["Assistance Requests"]
  node_sos["Emergency SOS<br/>[SosModal.tsx]"]
end

subgraph group_response["Response Operations"]
  node_alerts["Live Alerts<br/>[LiveAlerts.tsx]"]
  node_notifications["Notifications"]
  node_helpers["Helper Dispatch<br/>[HelpersPage.tsx]"]
  node_medical["Medical Help"]
  node_shelter_ops["Shelter Operations"]
  node_rescue["Rescue Command"]
  node_admin["Administration<br/>[AdminDashboard.tsx]"]
end

subgraph group_platform["Web Platform"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_data["Realtime Data Access<br/>[db.ts]"]
  node_app["App Router &amp; Live State<br/>[App.tsx]"]
  node_auth_page["Sign-in &amp; Registration<br/>[AuthPage.tsx]"]
  node_profile["User Profile<br/>[ProfilePage.tsx]"]
end

node_resident(("Residents &amp; Responders"))
node_serpapi["SerpAPI Places<br/>external service"]

node_esp32 -->|"sends telemetry"| node_gateway
node_simulator -->|"provides controls"| node_app
node_gateway -->|"ingests data"| node_firebase
node_gateway -->|"queries places"| node_serpapi
node_app -->|"wraps auth"| node_auth
node_auth -->|"authenticates and stores profiles"| node_firebase
node_app -->|"subscribes to live data"| node_data
node_data -.->|"reads and writes"| node_firebase
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_shelters
node_app -->|"routes to"| node_shelter_detail
node_app -->|"routes to"| node_evacuation
node_app -->|"routes to"| node_assistance
node_app -->|"renders"| node_sos
node_app -->|"routes to"| node_alerts
node_app -->|"routes to"| node_notifications
node_app -->|"routes to"| node_helpers
node_app -->|"routes to"| node_medical
node_app -->|"routes to"| node_shelter_ops
node_app -->|"routes to"| node_rescue
node_app -->|"routes to"| node_admin
node_app -->|"routes to"| node_auth_page
node_app -->|"routes to"| node_profile
node_resident -.->|"uses web app"| node_app
node_home -.->|"recommends shelters"| node_suitability
node_shelters -.->|"ranks options"| node_suitability
node_evacuation -.->|"computes departure window"| node_evacuation_engine
node_serpapi -.->|"returns place results"| node_gateway

click node_esp32 "https://github.com/yuchirozen/safehub/blob/main/firmware/SafeHub_ESP32_Node.ino"
click node_simulator "https://github.com/yuchirozen/safehub/blob/main/src/components/HardwareSimulator.tsx"
click node_gateway "https://github.com/yuchirozen/safehub/blob/main/server/index.ts"
click node_auth "https://github.com/yuchirozen/safehub/blob/main/src/services/auth.ts"
click node_data "https://github.com/yuchirozen/safehub/blob/main/src/services/db.ts"
click node_app "https://github.com/yuchirozen/safehub/blob/main/src/App.tsx"
click node_home "https://github.com/yuchirozen/safehub/blob/main/src/pages/EmergencyHome.tsx"
click node_shelters "https://github.com/yuchirozen/safehub/blob/main/src/pages/SheltersPage.tsx"
click node_shelter_detail "https://github.com/yuchirozen/safehub/blob/main/src/pages/ShelterDetailsPage.tsx"
click node_suitability "https://github.com/yuchirozen/safehub/blob/main/src/utils/suitability.ts"
click node_evacuation "https://github.com/yuchirozen/safehub/blob/main/src/pages/EvacuationGuidancePage.tsx"
click node_evacuation_engine "https://github.com/yuchirozen/safehub/blob/main/src/utils/evacuation.ts"
click node_assistance "https://github.com/yuchirozen/safehub/blob/main/src/pages/RequestAssistancePage.tsx"
click node_sos "https://github.com/yuchirozen/safehub/blob/main/src/components/SosModal.tsx"
click node_alerts "https://github.com/yuchirozen/safehub/blob/main/src/pages/LiveAlerts.tsx"
click node_notifications "https://github.com/yuchirozen/safehub/blob/main/src/pages/NotificationsPage.tsx"
click node_helpers "https://github.com/yuchirozen/safehub/blob/main/src/pages/HelpersPage.tsx"
click node_medical "https://github.com/yuchirozen/safehub/blob/main/src/pages/MedicalHelpPage.tsx"
click node_shelter_ops "https://github.com/yuchirozen/safehub/blob/main/src/pages/ShelterManagementPage.tsx"
click node_rescue "https://github.com/yuchirozen/safehub/blob/main/src/pages/RescueDashboard.tsx"
click node_admin "https://github.com/yuchirozen/safehub/blob/main/src/pages/AdminDashboard.tsx"
click node_auth_page "https://github.com/yuchirozen/safehub/blob/main/src/pages/AuthPage.tsx"
click node_profile "https://github.com/yuchirozen/safehub/blob/main/src/pages/ProfilePage.tsx"

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_esp32,node_simulator toneBlue
class node_gateway,node_firebase toneAmber
class node_home,node_shelters,node_shelter_detail,node_suitability,node_evacuation,node_evacuation_engine,node_assistance,node_sos,node_serpapi toneMint
class node_alerts,node_notifications,node_helpers,node_medical,node_shelter_ops,node_rescue,node_admin toneRose
class node_auth,node_data,node_app,node_auth_page,node_profile,node_resident toneIndigo
```

## Components

### Field Devices

- [ESP32 Node](https://github.com/yuchirozen/safehub/blob/main/firmware/SafeHub_ESP32_Node.ino): `firmware/SafeHub_ESP32_Node.ino`
- [Hardware Simulator](https://github.com/yuchirozen/safehub/blob/main/src/components/HardwareSimulator.tsx): `src/components/HardwareSimulator.tsx`

### Cloud Services

- [Ingestion Gateway](https://github.com/yuchirozen/safehub/blob/main/server/index.ts): `server/index.ts`
- **Firebase Auth & Firestore**

### Evacuation & Aid

- [Emergency Dashboard](https://github.com/yuchirozen/safehub/blob/main/src/pages/EmergencyHome.tsx): `src/pages/EmergencyHome.tsx`
- [Shelter Discovery](https://github.com/yuchirozen/safehub/blob/main/src/pages/SheltersPage.tsx): `src/pages/SheltersPage.tsx`
- [Shelter Details](https://github.com/yuchirozen/safehub/blob/main/src/pages/ShelterDetailsPage.tsx): `src/pages/ShelterDetailsPage.tsx`
- [Shelter Suitability](https://github.com/yuchirozen/safehub/blob/main/src/utils/suitability.ts): `src/utils/suitability.ts`
- [Evacuation Guidance](https://github.com/yuchirozen/safehub/blob/main/src/pages/EvacuationGuidancePage.tsx): `src/pages/EvacuationGuidancePage.tsx`
- [Departure Window Engine](https://github.com/yuchirozen/safehub/blob/main/src/utils/evacuation.ts): `src/utils/evacuation.ts`
- [Assistance Requests](https://github.com/yuchirozen/safehub/blob/main/src/pages/RequestAssistancePage.tsx): `src/pages/RequestAssistancePage.tsx`
- [Emergency SOS](https://github.com/yuchirozen/safehub/blob/main/src/components/SosModal.tsx): `src/components/SosModal.tsx`

### Response Operations

- [Live Alerts](https://github.com/yuchirozen/safehub/blob/main/src/pages/LiveAlerts.tsx): `src/pages/LiveAlerts.tsx`
- [Notifications](https://github.com/yuchirozen/safehub/blob/main/src/pages/NotificationsPage.tsx): `src/pages/NotificationsPage.tsx`
- [Helper Dispatch](https://github.com/yuchirozen/safehub/blob/main/src/pages/HelpersPage.tsx): `src/pages/HelpersPage.tsx`
- [Medical Help](https://github.com/yuchirozen/safehub/blob/main/src/pages/MedicalHelpPage.tsx): `src/pages/MedicalHelpPage.tsx`
- [Shelter Operations](https://github.com/yuchirozen/safehub/blob/main/src/pages/ShelterManagementPage.tsx): `src/pages/ShelterManagementPage.tsx`
- [Rescue Command](https://github.com/yuchirozen/safehub/blob/main/src/pages/RescueDashboard.tsx): `src/pages/RescueDashboard.tsx`
- [Administration](https://github.com/yuchirozen/safehub/blob/main/src/pages/AdminDashboard.tsx): `src/pages/AdminDashboard.tsx`

### Web Platform

- [Authentication](https://github.com/yuchirozen/safehub/blob/main/src/services/auth.ts): `src/services/auth.ts`
- [Realtime Data Access](https://github.com/yuchirozen/safehub/blob/main/src/services/db.ts): `src/services/db.ts`
- [App Router & Live State](https://github.com/yuchirozen/safehub/blob/main/src/App.tsx): `src/App.tsx`
- [Sign-in & Registration](https://github.com/yuchirozen/safehub/blob/main/src/pages/AuthPage.tsx): `src/pages/AuthPage.tsx`
- [User Profile](https://github.com/yuchirozen/safehub/blob/main/src/pages/ProfilePage.tsx): `src/pages/ProfilePage.tsx`

### Other components

- **Residents & Responders**
- **SerpAPI Places**: external service

## Connections

- ESP32 Node → Ingestion Gateway: sends telemetry (evidence: `README.md`)
- Hardware Simulator → App Router & Live State: provides controls (evidence: `src/App.tsx`)
- Ingestion Gateway → Firebase Auth & Firestore: ingests data (evidence: `README.md`)
- Ingestion Gateway → SerpAPI Places: queries places (evidence: `README.md`)
- App Router & Live State → Authentication: wraps auth (evidence: `src/App.tsx`)
- Authentication → Firebase Auth & Firestore: authenticates and stores profiles (evidence: `src/services/auth.ts`)
- App Router & Live State → Realtime Data Access: subscribes to live data (evidence: `src/App.tsx`)
- Realtime Data Access → Firebase Auth & Firestore: reads and writes
- App Router & Live State → Emergency Dashboard: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Shelter Discovery: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Shelter Details: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Evacuation Guidance: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Assistance Requests: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Emergency SOS: renders (evidence: `src/App.tsx`)
- App Router & Live State → Live Alerts: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Notifications: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Helper Dispatch: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Medical Help: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Shelter Operations: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Rescue Command: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Administration: routes to (evidence: `src/App.tsx`)
- App Router & Live State → Sign-in & Registration: routes to (evidence: `src/App.tsx`)
- App Router & Live State → User Profile: routes to (evidence: `src/App.tsx`)
- Residents & Responders → App Router & Live State: uses web app
- Emergency Dashboard → Shelter Suitability: recommends shelters
- Shelter Discovery → Shelter Suitability: ranks options
- Evacuation Guidance → Departure Window Engine: computes departure window
- SerpAPI Places → Ingestion Gateway: returns place results