# shadowincache/safeher architecture

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

- Interactive diagram: https://gitdiagram.com/shadowincache/safeher
- Repository: https://github.com/shadowincache/safeher

## Overview

SafeHer is a wearable-assisted emergency safety platform. Its primary flow is threat detection on a paired glove or phone, followed by threat fusion and an SOS incident, then independent contact fan-out and status reporting. The backend also provides authentication, journeys, nearby-safety tools, incident evidence and reports, and privacy controls. The README documents mobile and wearable behavior, but Flutter source is absent from the supplied tree; unsampled backend subsystems are shown at their listed paths. Connections are limited to excerpted references or README-documented flows.

Main entry points: [`mobile`](https://github.com/shadowincache/safeher/tree/main/mobile) (Mobile app), [`fastapi_app/routers/alerts.py`](https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/alerts.py) (Alert routes), [`fastapi_app/services/emergency_dispatch.py`](https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/emergency_dispatch.py) (Emergency dispatch), [`fastapi_app/main.py`](https://github.com/shadowincache/safeher/blob/main/fastapi_app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile and wearables"]
  node_mobile["Mobile app"]
  node_glove["Smart glove"]
  node_glasses["Smart glasses<br/>[thingProperties.h]"]
end

subgraph group_api["Backend API"]
  node_api["FastAPI app<br/>[main.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_realtime["Realtime messaging<br/>[realtime.py]"]
end

subgraph group_safety["Detection and response"]
  node_alerts["Alert routes<br/>[alerts.py]"]
  node_fusion["Threat fusion<br/>[threat_fusion.py]"]
  node_dispatch["Emergency dispatch"]
  node_journeys["Safe journeys<br/>[journeys.py]"]
  node_safety_tools["Nearby safety<br/>[safety.py]"]
  node_reports["Incident reports<br/>[incidents.py]"]
  node_media["Evidence media<br/>[media.py]"]
  node_processor["Event processor client"]
end

subgraph group_data["Identity and records"]
  node_users["User records<br/>[users.py]"]
  node_contacts["Emergency contacts"]
  node_security["Auth security<br/>[auth_security.py]"]
  node_models["Data models<br/>[models.py]"]
  node_database[("Database<br/>[db.py]")]
end

subgraph group_integrations["External services"]
  node_evidence_store["Evidence storage<br/>[evidence_store.py]"]
  node_event_processor["Event processor"]
  node_delivery["SMS, email, push<br/>[notifications.py]"]
end

node_person(("SafeHer user"))
node_contacts_external(("Emergency contacts"))
node_external_services["Maps and providers"]

node_person -->|"uses"| node_mobile
node_glove -->|"sends motion by BLE"| node_mobile
node_glasses -->|"streams video"| node_mobile
node_mobile -->|"REST and JWT"| node_api
node_api -->|"WebSocket and FCM"| node_mobile
node_api -->|"routes requests"| node_auth
node_api -->|"routes requests"| node_alerts
node_person -->|"triggers SOS"| node_alerts
node_alerts -->|"evaluates signals"| node_fusion
node_alerts -->|"submits threat"| node_processor
node_processor -->|"posts threat"| node_event_processor
node_alerts -->|"dispatches alert"| node_dispatch
node_dispatch -->|"loads recipients"| node_contacts
node_dispatch -->|"sends notifications"| node_delivery
node_delivery -->|"fans out SMS, email, push"| node_contacts_external
node_dispatch -->|"publishes updates"| node_realtime
node_mobile -->|"manages journeys"| node_journeys
node_mobile -->|"finds nearby safety"| node_safety_tools
node_mobile -->|"views incident history"| node_reports
node_mobile -->|"captures evidence"| node_media
node_media -.->|"stores evidence"| node_evidence_store
node_auth -->|"reads and creates users"| node_users
node_auth -->|"manages security state"| node_security
node_alerts -->|"persists incidents"| node_database
node_dispatch -->|"updates dispatch state"| node_database
node_database -->|"maps records"| node_models
node_journeys -.->|"uses location services"| node_external_services
node_safety_tools -->|"queries nearby places"| node_external_services

click node_mobile "https://github.com/shadowincache/safeher/tree/main/mobile"
click node_glove "https://github.com/shadowincache/safeher/blob/main/glove/firmware/SafeHer_Glove_V5_OnDevice/safeher_v5_model.cpp"
click node_glasses "https://github.com/shadowincache/safeher/blob/main/glasses/firmware/legacy_noise_alarm/thingProperties.h"
click node_api "https://github.com/shadowincache/safeher/blob/main/fastapi_app/main.py"
click node_auth "https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/auth.py"
click node_alerts "https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/alerts.py"
click node_fusion "https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/threat_fusion.py"
click node_dispatch "https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/emergency_dispatch.py"
click node_journeys "https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/journeys.py"
click node_safety_tools "https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/safety.py"
click node_reports "https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/incidents.py"
click node_media "https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/media.py"
click node_processor "https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/processor_client.py"
click node_users "https://github.com/shadowincache/safeher/blob/main/fastapi_app/repositories/users.py"
click node_contacts "https://github.com/shadowincache/safeher/blob/main/fastapi_app/repositories/emergency_contacts.py"
click node_security "https://github.com/shadowincache/safeher/blob/main/fastapi_app/repositories/auth_security.py"
click node_models "https://github.com/shadowincache/safeher/blob/main/fastapi_app/models.py"
click node_database "https://github.com/shadowincache/safeher/blob/main/fastapi_app/db.py"
click node_evidence_store "https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/evidence_store.py"
click node_event_processor "https://github.com/shadowincache/safeher/blob/main/deployment/docker/safeher_event_processor.py"
click node_delivery "https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/notifications.py"
click node_realtime "https://github.com/shadowincache/safeher/blob/main/fastapi_app/realtime.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_mobile,node_glove,node_glasses,node_person toneBlue
class node_api,node_auth,node_realtime toneAmber
class node_alerts,node_fusion,node_dispatch,node_journeys,node_safety_tools,node_reports,node_media,node_processor toneMint
class node_users,node_contacts,node_security,node_models,node_database toneRose
class node_evidence_store,node_event_processor,node_delivery,node_contacts_external,node_external_services toneIndigo
```

## Components

### Mobile and wearables

- [Mobile app](https://github.com/shadowincache/safeher/tree/main/mobile): `mobile`
- [Smart glove](https://github.com/shadowincache/safeher/blob/main/glove/firmware/SafeHer_Glove_V5_OnDevice/safeher_v5_model.cpp): `glove/firmware/SafeHer_Glove_V5_OnDevice/safeher_v5_model.cpp`
- [Smart glasses](https://github.com/shadowincache/safeher/blob/main/glasses/firmware/legacy_noise_alarm/thingProperties.h): `glasses/firmware/legacy_noise_alarm/thingProperties.h`

### Backend API

- [FastAPI app](https://github.com/shadowincache/safeher/blob/main/fastapi_app/main.py): `fastapi_app/main.py`
- [Authentication routes](https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/auth.py): `fastapi_app/routers/auth.py`
- [Realtime messaging](https://github.com/shadowincache/safeher/blob/main/fastapi_app/realtime.py): `fastapi_app/realtime.py`

### Detection and response

- [Alert routes](https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/alerts.py): `fastapi_app/routers/alerts.py`
- [Threat fusion](https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/threat_fusion.py): `fastapi_app/services/threat_fusion.py`
- [Emergency dispatch](https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/emergency_dispatch.py): `fastapi_app/services/emergency_dispatch.py`
- [Safe journeys](https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/journeys.py): `fastapi_app/routers/journeys.py`
- [Nearby safety](https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/safety.py): `fastapi_app/routers/safety.py`
- [Incident reports](https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/incidents.py): `fastapi_app/routers/incidents.py`
- [Evidence media](https://github.com/shadowincache/safeher/blob/main/fastapi_app/routers/media.py): `fastapi_app/routers/media.py`
- [Event processor client](https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/processor_client.py): `fastapi_app/services/processor_client.py`

### Identity and records

- [User records](https://github.com/shadowincache/safeher/blob/main/fastapi_app/repositories/users.py): `fastapi_app/repositories/users.py`
- [Emergency contacts](https://github.com/shadowincache/safeher/blob/main/fastapi_app/repositories/emergency_contacts.py): `fastapi_app/repositories/emergency_contacts.py`
- [Auth security](https://github.com/shadowincache/safeher/blob/main/fastapi_app/repositories/auth_security.py): `fastapi_app/repositories/auth_security.py`
- [Data models](https://github.com/shadowincache/safeher/blob/main/fastapi_app/models.py): `fastapi_app/models.py`
- [Database](https://github.com/shadowincache/safeher/blob/main/fastapi_app/db.py): `fastapi_app/db.py`

### External services

- [Evidence storage](https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/evidence_store.py): `fastapi_app/services/evidence_store.py`
- [Event processor](https://github.com/shadowincache/safeher/blob/main/deployment/docker/safeher_event_processor.py): `deployment/docker/safeher_event_processor.py`
- [SMS, email, push](https://github.com/shadowincache/safeher/blob/main/fastapi_app/services/notifications.py): `fastapi_app/services/notifications.py`

### Other components

- **SafeHer user**
- **Emergency contacts**
- **Maps and providers**

## Connections

- SafeHer user → Mobile app: uses
- Smart glove → Mobile app: sends motion by BLE
- Smart glasses → Mobile app: streams video
- Mobile app → FastAPI app: REST and JWT
- FastAPI app → Mobile app: WebSocket and FCM
- FastAPI app → Authentication routes: routes requests (evidence: `fastapi_app/main.py`)
- FastAPI app → Alert routes: routes requests (evidence: `fastapi_app/main.py`)
- SafeHer user → Alert routes: triggers SOS
- Alert routes → Threat fusion: evaluates signals (evidence: `fastapi_app/routers/alerts.py`)
- Alert routes → Event processor client: submits threat (evidence: `fastapi_app/routers/alerts.py`)
- Event processor client → Event processor: posts threat (evidence: `fastapi_app/services/processor_client.py`)
- Alert routes → Emergency dispatch: dispatches alert (evidence: `fastapi_app/routers/alerts.py`)
- Emergency dispatch → Emergency contacts: loads recipients (evidence: `fastapi_app/services/emergency_dispatch.py`)
- Emergency dispatch → SMS, email, push: sends notifications (evidence: `fastapi_app/services/emergency_dispatch.py`)
- SMS, email, push → Emergency contacts: fans out SMS, email, push
- Emergency dispatch → Realtime messaging: publishes updates (evidence: `fastapi_app/services/emergency_dispatch.py`)
- Mobile app → Safe journeys: manages journeys
- Mobile app → Nearby safety: finds nearby safety
- Mobile app → Incident reports: views incident history
- Mobile app → Evidence media: captures evidence
- Evidence media → Evidence storage: stores evidence
- Authentication routes → User records: reads and creates users (evidence: `fastapi_app/routers/auth.py`)
- Authentication routes → Auth security: manages security state (evidence: `fastapi_app/routers/auth.py`)
- Alert routes → Database: persists incidents (evidence: `fastapi_app/routers/alerts.py`)
- Emergency dispatch → Database: updates dispatch state (evidence: `fastapi_app/services/emergency_dispatch.py`)
- Database → Data models: maps records (evidence: `fastapi_app/db.py`)
- Safe journeys → Maps and providers: uses location services
- Nearby safety → Maps and providers: queries nearby places
