# arunachalam-2006/safe-her architecture

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

- Interactive diagram: https://gitdiagram.com/arunachalam-2006/safe-her
- Repository: https://github.com/arunachalam-2006/safe-her

## Overview

Safe-Her is a cross-platform personal-safety app backed by a FastAPI engine. The main journey is: a person checks nearby safety or plans a destination, the app requests safety data and route analysis, and the engine combines map, weather, and scoring services to return assessments. Other documented workflows include SOS alerts and live location, community reports and journey monitoring, plus government review of reports and SOS. The README documents several engine integrations not shown in source excerpts; those relationships are identified as documented rather than inferred from unsampled code.

Main entry points: [`safety-engine/main.py`](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/main.py) (FastAPI engine), [`safety-engine/routes/safety.py`](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/safety.py) (Route analysis API), [`components/SOSActiveScreen.jsx`](https://github.com/arunachalam-2006/safe-her/blob/version-5/components/SOSActiveScreen.jsx) (Active SOS screen), [`lib/safetyApi.js`](https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/safetyApi.js) (Safety API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Safety app"]
  node_home["Safety home<br/>[index.jsx]"]
  node_routes["Route planning<br/>[routes.jsx]"]
  node_journey["Journey monitoring<br/>[journey.jsx]"]
  node_spotapi["Safety API client<br/>[safetyApi.js]"]
  node_location["Location services<br/>[location.js]"]
end

subgraph group_emergency["Emergency response"]
  node_sos["SOS workflow<br/>[sos.js]"]
  node_sosview["Active SOS screen"]
  node_contacts["Emergency contacts"]
  node_tracking["Background tracking"]
  node_sharing["Alert sharing<br/>[alertSharing.js]"]
end

subgraph group_engine["Safety engine"]
  node_engine["FastAPI engine<br/>[main.py]"]
  node_spot["Spot safety route<br/>[spot_safety.py]"]
  node_safetyroute["Route analysis API<br/>[safety.py]"]
  node_scoring["Safety scoring"]
  node_features["Feature extraction<br/>[feature_service.py]"]
  node_osrm["Route provider<br/>[osrm_service.py]"]
  node_overpass["OSM data service"]
  node_weather["Weather service<br/>[weather_service.py]"]
end

subgraph group_civic["Community and civic"]
  node_reports["Hazard reports<br/>[reports.py]"]
  node_journeys["Journey records<br/>[journeys.py]"]
  node_govui["Government dashboard<br/>[index.jsx]"]
  node_govapi["Government API client<br/>[govApi.js]"]
  node_govroute["Government endpoints<br/>[government.py]"]
  node_database[("Engine persistence<br/>[db.py]")]
end

node_person(("App user"))
node_osrmservice{{"OSRM"}}
node_osmservice{{"OpenStreetMap"}}
node_weatherservice{{"Open-Meteo"}}

node_person -->|"checks safety"| node_home
node_person -->|"plans route"| node_routes
node_home -->|"requests spot data"| node_spotapi
node_home -.->|"requests SOS"| node_sos
node_routes -->|"searches and routes"| node_location
node_routes -->|"analyzes route"| node_spotapi
node_spotapi -.->|"sends API requests"| node_engine
node_spotapi -->|"gets location"| node_location
node_engine -->|"registers route"| node_spot
node_engine -->|"registers route"| node_safetyroute
node_spot -->|"queries nearby places"| node_overpass
node_spot -->|"fetches conditions"| node_weather
node_safetyroute -.->|"requests route options"| node_osrm
node_safetyroute -.->|"gets map features"| node_overpass
node_safetyroute -.->|"gets weather factors"| node_weather
node_safetyroute -.->|"normalizes features"| node_features
node_safetyroute -.->|"scores routes"| node_scoring
node_osrm -.->|"queries routes"| node_osrmservice
node_overpass -->|"queries map data"| node_osmservice
node_weather -.->|"fetches weather"| node_weatherservice
node_person -->|"confirms alert"| node_sosview
node_sosview -->|"activates SOS"| node_sos
node_sos -->|"loads contacts"| node_contacts
node_sos -->|"starts tracking"| node_tracking
node_sosview -->|"reads latest location"| node_tracking
node_sosview -->|"shares alert"| node_sharing
node_person -->|"monitors journey"| node_journey
node_person -->|"submits hazard"| node_reports
node_person -->|"reviews incidents"| node_govui
node_govui -->|"loads reports and SOS"| node_govapi
node_govapi -->|"calls endpoints"| node_govroute
node_engine -->|"registers route"| node_reports
node_engine -->|"registers route"| node_journeys
node_engine -->|"registers route"| node_govroute
node_govroute -->|"uses persistence"| node_database

click node_home "https://github.com/arunachalam-2006/safe-her/blob/version-5/app/(tabs)/index.jsx"
click node_routes "https://github.com/arunachalam-2006/safe-her/blob/version-5/app/(tabs)/routes.jsx"
click node_journey "https://github.com/arunachalam-2006/safe-her/blob/version-5/app/(tabs)/journey.jsx"
click node_spotapi "https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/safetyApi.js"
click node_location "https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/location.js"
click node_sos "https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/sos.js"
click node_sosview "https://github.com/arunachalam-2006/safe-her/blob/version-5/components/SOSActiveScreen.jsx"
click node_contacts "https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/emergencyContacts.js"
click node_tracking "https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/backgroundLocationTask.js"
click node_sharing "https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/alertSharing.js"
click node_engine "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/main.py"
click node_spot "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/spot_safety.py"
click node_safetyroute "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/safety.py"
click node_scoring "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/engine/ruleBasedScoring.py"
click node_features "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/services/feature_service.py"
click node_osrm "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/services/osrm_service.py"
click node_overpass "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/services/overpass_service.py"
click node_weather "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/services/weather_service.py"
click node_reports "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/reports.py"
click node_journeys "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/journeys.py"
click node_govui "https://github.com/arunachalam-2006/safe-her/blob/version-5/app/(gov)/index.jsx"
click node_govapi "https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/government/govApi.js"
click node_govroute "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/government.py"
click node_database "https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/db.py"

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_home,node_routes,node_journey,node_spotapi,node_location,node_person toneBlue
class node_sos,node_sosview,node_contacts,node_tracking,node_sharing toneAmber
class node_engine,node_spot,node_safetyroute,node_scoring,node_features,node_osrm,node_overpass,node_weather toneMint
class node_reports,node_journeys,node_govui,node_govapi,node_govroute,node_database toneRose
class node_osrmservice,node_osmservice,node_weatherservice toneIndigo
```

## Components

### Safety app

- [Safety home](https://github.com/arunachalam-2006/safe-her/blob/version-5/app/(tabs)/index.jsx): `app/(tabs)/index.jsx`
- [Route planning](https://github.com/arunachalam-2006/safe-her/blob/version-5/app/(tabs)/routes.jsx): `app/(tabs)/routes.jsx`
- [Journey monitoring](https://github.com/arunachalam-2006/safe-her/blob/version-5/app/(tabs)/journey.jsx): `app/(tabs)/journey.jsx`
- [Safety API client](https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/safetyApi.js): `lib/safetyApi.js`
- [Location services](https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/location.js): `lib/location.js`

### Emergency response

- [SOS workflow](https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/sos.js): `lib/sos.js`
- [Active SOS screen](https://github.com/arunachalam-2006/safe-her/blob/version-5/components/SOSActiveScreen.jsx): `components/SOSActiveScreen.jsx`
- [Emergency contacts](https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/emergencyContacts.js): `lib/emergencyContacts.js`
- [Background tracking](https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/backgroundLocationTask.js): `lib/backgroundLocationTask.js`
- [Alert sharing](https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/alertSharing.js): `lib/alertSharing.js`

### Safety engine

- [FastAPI engine](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/main.py): `safety-engine/main.py`
- [Spot safety route](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/spot_safety.py): `safety-engine/routes/spot_safety.py`
- [Route analysis API](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/safety.py): `safety-engine/routes/safety.py`
- [Safety scoring](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/engine/ruleBasedScoring.py): `safety-engine/engine/ruleBasedScoring.py`
- [Feature extraction](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/services/feature_service.py): `safety-engine/services/feature_service.py`
- [Route provider](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/services/osrm_service.py): `safety-engine/services/osrm_service.py`
- [OSM data service](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/services/overpass_service.py): `safety-engine/services/overpass_service.py`
- [Weather service](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/services/weather_service.py): `safety-engine/services/weather_service.py`

### Community and civic

- [Hazard reports](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/reports.py): `safety-engine/routes/reports.py`
- [Journey records](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/journeys.py): `safety-engine/routes/journeys.py`
- [Government dashboard](https://github.com/arunachalam-2006/safe-her/blob/version-5/app/(gov)/index.jsx): `app/(gov)/index.jsx`
- [Government API client](https://github.com/arunachalam-2006/safe-her/blob/version-5/lib/government/govApi.js): `lib/government/govApi.js`
- [Government endpoints](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/routes/government.py): `safety-engine/routes/government.py`
- [Engine persistence](https://github.com/arunachalam-2006/safe-her/blob/version-5/safety-engine/db.py): `safety-engine/db.py`

### Other components

- **App user**
- **OSRM**
- **OpenStreetMap**
- **Open-Meteo**

## Connections

- App user → Safety home: checks safety (evidence: `README.md`)
- App user → Route planning: plans route (evidence: `README.md`)
- Safety home → Safety API client: requests spot data (evidence: `app/(tabs)/index.jsx`)
- Safety home → SOS workflow: requests SOS (evidence: `app/(tabs)/index.jsx`)
- Route planning → Location services: searches and routes (evidence: `app/(tabs)/routes.jsx`)
- Route planning → Safety API client: analyzes route (evidence: `app/(tabs)/routes.jsx`)
- Safety API client → FastAPI engine: sends API requests
- Safety API client → Location services: gets location (evidence: `lib/safetyApi.js`)
- FastAPI engine → Spot safety route: registers route (evidence: `safety-engine/main.py`)
- FastAPI engine → Route analysis API: registers route (evidence: `safety-engine/main.py`)
- Spot safety route → OSM data service: queries nearby places (evidence: `safety-engine/routes/spot_safety.py`)
- Spot safety route → Weather service: fetches conditions (evidence: `safety-engine/routes/spot_safety.py`)
- Route analysis API → Route provider: requests route options (evidence: `README.md`)
- Route analysis API → OSM data service: gets map features (evidence: `README.md`)
- Route analysis API → Weather service: gets weather factors (evidence: `README.md`)
- Route analysis API → Feature extraction: normalizes features (evidence: `README.md`)
- Route analysis API → Safety scoring: scores routes (evidence: `README.md`)
- Route provider → OSRM: queries routes (evidence: `README.md`)
- OSM data service → OpenStreetMap: queries map data (evidence: `safety-engine/services/overpass_service.py`)
- Weather service → Open-Meteo: fetches weather (evidence: `README.md`)
- App user → Active SOS screen: confirms alert (evidence: `README.md`)
- Active SOS screen → SOS workflow: activates SOS (evidence: `components/SOSActiveScreen.jsx`)
- SOS workflow → Emergency contacts: loads contacts (evidence: `lib/sos.js`)
- SOS workflow → Background tracking: starts tracking (evidence: `lib/sos.js`)
- Active SOS screen → Background tracking: reads latest location (evidence: `components/SOSActiveScreen.jsx`)
- Active SOS screen → Alert sharing: shares alert (evidence: `components/SOSActiveScreen.jsx`)
- App user → Journey monitoring: monitors journey (evidence: `README.md`)
- App user → Hazard reports: submits hazard (evidence: `README.md`)
- App user → Government dashboard: reviews incidents (evidence: `README.md`)
- Government dashboard → Government API client: loads reports and SOS (evidence: `app/(gov)/index.jsx`)
- Government API client → Government endpoints: calls endpoints (evidence: `lib/government/govApi.js`)
- FastAPI engine → Hazard reports: registers route (evidence: `safety-engine/main.py`)
- FastAPI engine → Journey records: registers route (evidence: `safety-engine/main.py`)
- FastAPI engine → Government endpoints: registers route (evidence: `safety-engine/main.py`)
- Government endpoints → Engine persistence: uses persistence (evidence: `safety-engine/routes/government.py`)
