# ay178/sos architecture

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

- Interactive diagram: https://gitdiagram.com/ay178/sos
- Repository: https://github.com/ay178/sos

## Overview

RoadSoS AI coordinates an emergency response from a mobile SOS flow: incident intake and creation, AI severity assessment, hospital ranking, ambulance dispatch, and alerts to hospitals and family. Hospital staff manage capacity and incoming alerts; families can follow a shareable tracking page, while users can sign in and maintain medical profiles. The README documents the end-to-end workflow and several capabilities whose source was not sampled; those links are shown as documented rather than inferred from imports.

Main entry points: [`supabase/migrations/001_schema.sql`](https://github.com/ay178/sos/blob/main/supabase/migrations/001_schema.sql) (Postgres data), [`app/page.tsx`](https://github.com/ay178/sos/blob/main/app/page.tsx) (SOS app), [`app/api/dispatch/route.ts`](https://github.com/ay178/sos/blob/main/app/api/dispatch/route.ts) (Ambulance dispatch), [`lib/notify.ts`](https://github.com/ay178/sos/blob/main/lib/notify.ts) (Alert messaging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_response["Emergency response"]
  node_mobile["SOS app<br/>[page.tsx]"]
  node_tracking["Live tracking<br/>[page.tsx]"]
  node_profileui["Medical profile UI<br/>[page.tsx]"]
  node_auth["Sign-in<br/>[page.tsx]"]
end

subgraph group_services["Response services"]
  node_incident["Incident intake<br/>[route.ts]"]
  node_severity["Severity analysis<br/>[route.ts]"]
  node_hospitalrank["Hospital ranking<br/>[route.ts]"]
  node_trs["TRS engine<br/>[trs.ts]"]
  node_dispatch["Ambulance dispatch<br/>[route.ts]"]
  node_notify["Alert messaging<br/>[notify.ts]"]
  node_profileapi["Profile service<br/>[route.ts]"]
  node_inference["Inference service"]
  node_model["Severity model"]
end

subgraph group_operations["Care operations"]
  node_dashboard["Hospital dashboard<br/>[page.tsx]"]
end

subgraph group_platform["Data and identity"]
  node_supabase["Supabase clients<br/>[supabase.ts]"]
  node_browserclient["Browser client<br/>[client.ts]"]
  node_serverclient["Server client<br/>[server.ts]"]
  node_database[("Postgres data<br/>[001_schema.sql]")]
  node_types["Domain types<br/>[index.ts]"]
end

node_caller(("SOS reporter"))
node_claude{{"Claude AI"}}
node_twilio{{"Twilio"}}
node_family(("Family contact"))
node_hospitalstaff(("Hospital staff"))

node_caller -->|"starts SOS"| node_mobile
node_mobile -->|"creates incident"| node_incident
node_incident -->|"writes incident"| node_database
node_mobile -->|"requests analysis"| node_severity
node_severity -->|"analyzes severity"| node_claude
node_mobile -->|"requests ranking"| node_hospitalrank
node_hospitalrank -->|"reads hospitals"| node_database
node_hospitalrank -->|"ranks hospitals"| node_trs
node_mobile -->|"requests dispatch"| node_dispatch
node_dispatch -->|"reads and updates"| node_database
node_dispatch -->|"scores selected hospital"| node_trs
node_dispatch -->|"sends alerts"| node_notify
node_notify -->|"sends SMS and WhatsApp"| node_twilio
node_notify -->|"alerts family"| node_family
node_notify -->|"alerts hospital"| node_hospitalstaff
node_family -->|"follows incident"| node_tracking
node_hospitalstaff -->|"manages capacity"| node_dashboard
node_dashboard -->|"updates hospital data"| node_database
node_profileui -.->|"manages profile"| node_profileapi
node_profileapi -->|"upserts profile"| node_database
node_auth -->|"uses auth client"| node_supabase
node_supabase -->|"re-exports client"| node_browserclient
node_browserclient -.->|"connects to data"| node_database
node_supabase -.->|"creates service connection"| node_database
node_serverclient -.->|"creates server connection"| node_database
node_inference -.->|"loads model"| node_model

click node_mobile "https://github.com/ay178/sos/blob/main/app/page.tsx"
click node_incident "https://github.com/ay178/sos/blob/main/app/api/sos/route.ts"
click node_severity "https://github.com/ay178/sos/blob/main/app/api/analyze/route.ts"
click node_hospitalrank "https://github.com/ay178/sos/blob/main/app/api/trs/route.ts"
click node_trs "https://github.com/ay178/sos/blob/main/lib/trs.ts"
click node_dispatch "https://github.com/ay178/sos/blob/main/app/api/dispatch/route.ts"
click node_notify "https://github.com/ay178/sos/blob/main/lib/notify.ts"
click node_tracking "https://github.com/ay178/sos/blob/main/app/tracking/%5Bid%5D/page.tsx"
click node_dashboard "https://github.com/ay178/sos/blob/main/app/hospital/page.tsx"
click node_profileui "https://github.com/ay178/sos/blob/main/app/page.tsx"
click node_profileapi "https://github.com/ay178/sos/blob/main/app/api/profile/route.ts"
click node_auth "https://github.com/ay178/sos/blob/main/app/auth/page.tsx"
click node_supabase "https://github.com/ay178/sos/blob/main/lib/supabase.ts"
click node_browserclient "https://github.com/ay178/sos/blob/main/utils/supabase/client.ts"
click node_serverclient "https://github.com/ay178/sos/blob/main/utils/supabase/server.ts"
click node_database "https://github.com/ay178/sos/blob/main/supabase/migrations/001_schema.sql"
click node_types "https://github.com/ay178/sos/blob/main/types/index.ts"
click node_inference "https://github.com/ay178/sos/blob/main/inference_server.py"
click node_model "https://github.com/ay178/sos/blob/main/model/roadsos_accident_severity_model.keras"

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_mobile,node_tracking,node_profileui,node_auth toneBlue
class node_incident,node_severity,node_hospitalrank,node_trs,node_dispatch,node_notify,node_profileapi,node_inference,node_model toneAmber
class node_dashboard toneMint
class node_supabase,node_browserclient,node_serverclient,node_database,node_types toneRose
class node_caller,node_claude,node_twilio,node_family,node_hospitalstaff toneIndigo
```

## Components

### Emergency response

- [SOS app](https://github.com/ay178/sos/blob/main/app/page.tsx): `app/page.tsx`
- [Live tracking](https://github.com/ay178/sos/blob/main/app/tracking/%5Bid%5D/page.tsx): `app/tracking/[id]/page.tsx`
- [Medical profile UI](https://github.com/ay178/sos/blob/main/app/page.tsx): `app/page.tsx`
- [Sign-in](https://github.com/ay178/sos/blob/main/app/auth/page.tsx): `app/auth/page.tsx`

### Response services

- [Incident intake](https://github.com/ay178/sos/blob/main/app/api/sos/route.ts): `app/api/sos/route.ts`
- [Severity analysis](https://github.com/ay178/sos/blob/main/app/api/analyze/route.ts): `app/api/analyze/route.ts`
- [Hospital ranking](https://github.com/ay178/sos/blob/main/app/api/trs/route.ts): `app/api/trs/route.ts`
- [TRS engine](https://github.com/ay178/sos/blob/main/lib/trs.ts): `lib/trs.ts`
- [Ambulance dispatch](https://github.com/ay178/sos/blob/main/app/api/dispatch/route.ts): `app/api/dispatch/route.ts`
- [Alert messaging](https://github.com/ay178/sos/blob/main/lib/notify.ts): `lib/notify.ts`
- [Profile service](https://github.com/ay178/sos/blob/main/app/api/profile/route.ts): `app/api/profile/route.ts`
- [Inference service](https://github.com/ay178/sos/blob/main/inference_server.py): `inference_server.py`
- [Severity model](https://github.com/ay178/sos/blob/main/model/roadsos_accident_severity_model.keras): `model/roadsos_accident_severity_model.keras`

### Care operations

- [Hospital dashboard](https://github.com/ay178/sos/blob/main/app/hospital/page.tsx): `app/hospital/page.tsx`

### Data and identity

- [Supabase clients](https://github.com/ay178/sos/blob/main/lib/supabase.ts): `lib/supabase.ts`
- [Browser client](https://github.com/ay178/sos/blob/main/utils/supabase/client.ts): `utils/supabase/client.ts`
- [Server client](https://github.com/ay178/sos/blob/main/utils/supabase/server.ts): `utils/supabase/server.ts`
- [Postgres data](https://github.com/ay178/sos/blob/main/supabase/migrations/001_schema.sql): `supabase/migrations/001_schema.sql`
- [Domain types](https://github.com/ay178/sos/blob/main/types/index.ts): `types/index.ts`

### Other components

- **SOS reporter**
- **Claude AI**
- **Twilio**
- **Family contact**
- **Hospital staff**

## Connections

- SOS reporter → SOS app: starts SOS (evidence: `README.md`)
- SOS app → Incident intake: creates incident (evidence: `README.md`)
- Incident intake → Postgres data: writes incident (evidence: `app/api/sos/route.ts`)
- SOS app → Severity analysis: requests analysis (evidence: `README.md`)
- Severity analysis → Claude AI: analyzes severity (evidence: `README.md`)
- SOS app → Hospital ranking: requests ranking (evidence: `app/page.tsx`)
- Hospital ranking → Postgres data: reads hospitals (evidence: `app/api/trs/route.ts`)
- Hospital ranking → TRS engine: ranks hospitals (evidence: `app/api/trs/route.ts`)
- SOS app → Ambulance dispatch: requests dispatch (evidence: `README.md`)
- Ambulance dispatch → Postgres data: reads and updates (evidence: `app/api/dispatch/route.ts`)
- Ambulance dispatch → TRS engine: scores selected hospital (evidence: `app/api/dispatch/route.ts`)
- Ambulance dispatch → Alert messaging: sends alerts (evidence: `app/api/dispatch/route.ts`)
- Alert messaging → Twilio: sends SMS and WhatsApp (evidence: `lib/notify.ts`)
- Alert messaging → Family contact: alerts family (evidence: `lib/notify.ts`)
- Alert messaging → Hospital staff: alerts hospital (evidence: `lib/notify.ts`)
- Family contact → Live tracking: follows incident (evidence: `README.md`)
- Hospital staff → Hospital dashboard: manages capacity (evidence: `README.md`)
- Hospital dashboard → Postgres data: updates hospital data (evidence: `app/hospital/page.tsx`)
- Medical profile UI → Profile service: manages profile
- Profile service → Postgres data: upserts profile (evidence: `app/api/profile/route.ts`)
- Sign-in → Supabase clients: uses auth client (evidence: `README.md`)
- Supabase clients → Browser client: re-exports client (evidence: `lib/supabase.ts`)
- Browser client → Postgres data: connects to data
- Supabase clients → Postgres data: creates service connection
- Server client → Postgres data: creates server connection
- Inference service → Severity model: loads model
