# xreep/raksha architecture

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

- Interactive diagram: https://gitdiagram.com/xreep/raksha
- Repository: https://github.com/xreep/raksha

## Overview

PHC is a privacy-preserving mobile health companion: it collects on-device readings, combines them with local environmental context, assesses risk, and presents dashboard/history results or initiates an SOS. The README documents the end-to-end pipeline and major features; sampled source confirms key orchestration boundaries. The relay’s endpoint wiring is sampled, but most app hooks and several subsystems are represented from the README and file tree.

Main entry points: [`relay/src/dispatch.ts`](https://github.com/xreep/raksha/blob/master/relay/src/dispatch.ts) (Channel dispatch), [`src/app/index.tsx`](https://github.com/xreep/raksha/blob/master/src/app/index.tsx) (Dashboard), [`src/sos/deliver.ts`](https://github.com/xreep/raksha/blob/master/src/sos/deliver.ts) (SOS orchestration), [`src/environment/service.ts`](https://github.com/xreep/raksha/blob/master/src/environment/service.ts) (Environment feed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Mobile experience"]
  node_dashboard["Dashboard<br/>[index.tsx]"]
  node_trends["Trends screen<br/>[trends.tsx]"]
  node_settings["Settings<br/>[provider.tsx]"]
  node_community["Community summary<br/>[aggregate.ts]"]
end

subgraph group_assessment["Sensing and assessment"]
  node_sensors["Sensor ingestion<br/>[provider.tsx]"]
  node_store[("Reading store<br/>[sqlite.ts]")]
  node_risk["Risk engine<br/>[assess.ts]"]
end

subgraph group_context["Context and community"]
  node_environment["Environment feed<br/>[service.ts]"]
  node_envcache[("Environment cache<br/>[cache.ts]")]
  node_communitylogic["Community aggregation<br/>[aggregate.ts]"]
  node_advisories["Preparedness advice<br/>[preparedness.ts]"]
end

subgraph group_emergency["Emergency response"]
  node_alerts["Local alerts<br/>[notify.ts]"]
  node_sos["SOS orchestration<br/>[deliver.ts]"]
  node_location["SOS location<br/>[location.ts]"]
  node_relayapp["App relay client<br/>[relay.ts]"]
end

subgraph group_relay["SOS relay"]
  node_worker["Relay API<br/>[index.ts]"]
  node_dispatch["Channel dispatch<br/>[dispatch.ts]"]
  node_telegram["Telegram adapter<br/>[telegram.ts]"]
  node_textbelt["Textbelt adapter<br/>[textbelt.ts]"]
  node_twilio["Twilio adapter<br/>[twilio.ts]"]
  node_fcm["FCM adapter<br/>[fcm.ts]"]
  node_linking["Telegram linking<br/>[link.ts]"]
end

node_person(("Phone user"))
node_healthconnect(("Health Connect"))
node_motion(("Phone motion sensor"))
node_weather(("OpenWeatherMap"))
node_sms(("Native SMS composer"))
node_provider(("Delivery providers"))
node_linkkv[("Link token store")]

node_person -->|"views"| node_dashboard
node_person -->|"configures"| node_settings
node_healthconnect -->|"supplies vitals"| node_sensors
node_motion -->|"supplies motion"| node_sensors
node_sensors -->|"persists readings"| node_store
node_store -->|"provides history"| node_risk
node_dashboard -->|"requests assessment"| node_risk
node_environment -->|"provides context"| node_risk
node_environment -->|"fetches weather/AQI"| node_weather
node_environment -->|"writes snapshot"| node_envcache
node_envcache -.->|"fallback reads"| node_environment
node_dashboard -->|"plans notifications"| node_alerts
node_dashboard -->|"hands off triggers"| node_sos
node_sos -->|"resolves location"| node_location
node_location -->|"gets device fix"| node_person
node_sos -->|"requests delivery"| node_relayapp
node_relayapp -->|"posts SOS"| node_worker
node_sos -.->|"opens fallback"| node_sms
node_trends -->|"reads history"| node_store
node_person -->|"views summary"| node_community
node_community -->|"summarizes cohort"| node_communitylogic
node_person -->|"reads guidance"| node_advisories
node_worker -->|"dispatches alert"| node_dispatch
node_dispatch -->|"sends message"| node_telegram
node_dispatch -->|"sends SMS"| node_textbelt
node_dispatch -->|"sends SMS"| node_twilio
node_dispatch -->|"sends notification"| node_fcm
node_telegram -->|"calls API"| node_provider
node_textbelt -->|"calls API"| node_provider
node_twilio -->|"calls API"| node_provider
node_fcm -->|"calls API"| node_provider
node_worker -->|"handles linking"| node_linking
node_linking -->|"redeems token"| node_linkkv

click node_dashboard "https://github.com/xreep/raksha/blob/master/src/app/index.tsx"
click node_trends "https://github.com/xreep/raksha/blob/master/src/app/trends.tsx"
click node_settings "https://github.com/xreep/raksha/blob/master/src/settings/provider.tsx"
click node_community "https://github.com/xreep/raksha/blob/master/src/community/aggregate.ts"
click node_sensors "https://github.com/xreep/raksha/blob/master/src/sensors/provider.tsx"
click node_store "https://github.com/xreep/raksha/blob/master/src/store/sqlite.ts"
click node_risk "https://github.com/xreep/raksha/blob/master/src/risk/assess.ts"
click node_environment "https://github.com/xreep/raksha/blob/master/src/environment/service.ts"
click node_envcache "https://github.com/xreep/raksha/blob/master/src/environment/cache.ts"
click node_communitylogic "https://github.com/xreep/raksha/blob/master/src/community/aggregate.ts"
click node_advisories "https://github.com/xreep/raksha/blob/master/src/advisories/preparedness.ts"
click node_alerts "https://github.com/xreep/raksha/blob/master/src/alerts/notify.ts"
click node_sos "https://github.com/xreep/raksha/blob/master/src/sos/deliver.ts"
click node_location "https://github.com/xreep/raksha/blob/master/src/sos/location.ts"
click node_relayapp "https://github.com/xreep/raksha/blob/master/src/sos/relay.ts"
click node_worker "https://github.com/xreep/raksha/blob/master/relay/src/index.ts"
click node_dispatch "https://github.com/xreep/raksha/blob/master/relay/src/dispatch.ts"
click node_telegram "https://github.com/xreep/raksha/blob/master/relay/src/adapters/telegram.ts"
click node_textbelt "https://github.com/xreep/raksha/blob/master/relay/src/adapters/textbelt.ts"
click node_twilio "https://github.com/xreep/raksha/blob/master/relay/src/adapters/twilio.ts"
click node_fcm "https://github.com/xreep/raksha/blob/master/relay/src/adapters/fcm.ts"
click node_linking "https://github.com/xreep/raksha/blob/master/relay/src/link.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_dashboard,node_trends,node_settings,node_community,node_person toneBlue
class node_sensors,node_store,node_risk,node_linkkv toneAmber
class node_environment,node_envcache,node_communitylogic,node_advisories toneMint
class node_alerts,node_sos,node_location,node_relayapp toneRose
class node_worker,node_dispatch,node_telegram,node_textbelt,node_twilio,node_fcm,node_linking,node_healthconnect,node_motion,node_weather,node_sms,node_provider toneIndigo
```

## Components

### Mobile experience

- [Dashboard](https://github.com/xreep/raksha/blob/master/src/app/index.tsx): `src/app/index.tsx`
- [Trends screen](https://github.com/xreep/raksha/blob/master/src/app/trends.tsx): `src/app/trends.tsx`
- [Settings](https://github.com/xreep/raksha/blob/master/src/settings/provider.tsx): `src/settings/provider.tsx`
- [Community summary](https://github.com/xreep/raksha/blob/master/src/community/aggregate.ts): `src/community/aggregate.ts`

### Sensing and assessment

- [Sensor ingestion](https://github.com/xreep/raksha/blob/master/src/sensors/provider.tsx): `src/sensors/provider.tsx`
- [Reading store](https://github.com/xreep/raksha/blob/master/src/store/sqlite.ts): `src/store/sqlite.ts`
- [Risk engine](https://github.com/xreep/raksha/blob/master/src/risk/assess.ts): `src/risk/assess.ts`

### Context and community

- [Environment feed](https://github.com/xreep/raksha/blob/master/src/environment/service.ts): `src/environment/service.ts`
- [Environment cache](https://github.com/xreep/raksha/blob/master/src/environment/cache.ts): `src/environment/cache.ts`
- [Community aggregation](https://github.com/xreep/raksha/blob/master/src/community/aggregate.ts): `src/community/aggregate.ts`
- [Preparedness advice](https://github.com/xreep/raksha/blob/master/src/advisories/preparedness.ts): `src/advisories/preparedness.ts`

### Emergency response

- [Local alerts](https://github.com/xreep/raksha/blob/master/src/alerts/notify.ts): `src/alerts/notify.ts`
- [SOS orchestration](https://github.com/xreep/raksha/blob/master/src/sos/deliver.ts): `src/sos/deliver.ts`
- [SOS location](https://github.com/xreep/raksha/blob/master/src/sos/location.ts): `src/sos/location.ts`
- [App relay client](https://github.com/xreep/raksha/blob/master/src/sos/relay.ts): `src/sos/relay.ts`

### SOS relay

- [Relay API](https://github.com/xreep/raksha/blob/master/relay/src/index.ts): `relay/src/index.ts`
- [Channel dispatch](https://github.com/xreep/raksha/blob/master/relay/src/dispatch.ts): `relay/src/dispatch.ts`
- [Telegram adapter](https://github.com/xreep/raksha/blob/master/relay/src/adapters/telegram.ts): `relay/src/adapters/telegram.ts`
- [Textbelt adapter](https://github.com/xreep/raksha/blob/master/relay/src/adapters/textbelt.ts): `relay/src/adapters/textbelt.ts`
- [Twilio adapter](https://github.com/xreep/raksha/blob/master/relay/src/adapters/twilio.ts): `relay/src/adapters/twilio.ts`
- [FCM adapter](https://github.com/xreep/raksha/blob/master/relay/src/adapters/fcm.ts): `relay/src/adapters/fcm.ts`
- [Telegram linking](https://github.com/xreep/raksha/blob/master/relay/src/link.ts): `relay/src/link.ts`

### Other components

- **Phone user**
- **Health Connect**
- **Phone motion sensor**
- **OpenWeatherMap**
- **Native SMS composer**
- **Delivery providers**
- **Link token store**

## Connections

- Phone user → Dashboard: views
- Phone user → Settings: configures
- Health Connect → Sensor ingestion: supplies vitals
- Phone motion sensor → Sensor ingestion: supplies motion
- Sensor ingestion → Reading store: persists readings
- Reading store → Risk engine: provides history
- Dashboard → Risk engine: requests assessment
- Environment feed → Risk engine: provides context
- Environment feed → OpenWeatherMap: fetches weather/AQI
- Environment feed → Environment cache: writes snapshot
- Environment cache → Environment feed: fallback reads
- Dashboard → Local alerts: plans notifications
- Dashboard → SOS orchestration: hands off triggers
- SOS orchestration → SOS location: resolves location
- SOS location → Phone user: gets device fix
- SOS orchestration → App relay client: requests delivery
- App relay client → Relay API: posts SOS
- SOS orchestration → Native SMS composer: opens fallback
- Trends screen → Reading store: reads history
- Phone user → Community summary: views summary
- Community summary → Community aggregation: summarizes cohort
- Phone user → Preparedness advice: reads guidance
- Relay API → Channel dispatch: dispatches alert
- Channel dispatch → Telegram adapter: sends message
- Channel dispatch → Textbelt adapter: sends SMS
- Channel dispatch → Twilio adapter: sends SMS
- Channel dispatch → FCM adapter: sends notification
- Telegram adapter → Delivery providers: calls API
- Textbelt adapter → Delivery providers: calls API
- Twilio adapter → Delivery providers: calls API
- FCM adapter → Delivery providers: calls API
- Relay API → Telegram linking: handles linking
- Telegram linking → Link token store: redeems token