# vizzie8/safeguard architecture

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

- Interactive diagram: https://gitdiagram.com/vizzie8/safeguard
- Repository: https://github.com/vizzie8/safeguard

## Overview

SafeGuard is a personal-safety application with a React SPA and a standalone vanilla-JS prototype. The main user flow starts at the safety dashboard: users configure triggers and contacts, raise an SOS, share location and alert recipients, while authenticated events are logged for the admin dashboard. A separate WebRTC flow relays signaling through the Node server but sends media peer-to-peer. The README documents the prototype’s additional scream, impact, and device-close triggers, risk-zone map, and emergency-service alert tier; source excerpts chiefly evidence the React, API, and signaling paths.

Main entry points: [`frontend/src/pages/Home.tsx`](https://github.com/vizzie8/safeguard/blob/main/frontend/src/pages/Home.tsx) (Safety dashboard), [`backend-node/src/server.ts`](https://github.com/vizzie8/safeguard/blob/main/backend-node/src/server.ts) (REST and signaling), [`app.js`](https://github.com/vizzie8/safeguard/blob/main/app.js) (Vanilla prototype), [`backend-node/src/routes/contactRoutes.ts`](https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/contactRoutes.ts) (Emergency contacts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Safety clients"]
  node_react["React application<br/>[App.tsx]"]
  node_home["Safety dashboard<br/>[Home.tsx]"]
  node_settings["Safety settings"]
  node_voice["Voice detection"]
  node_fall["Impact detection"]
  node_location["Location tracking"]
  node_map["Risk-zone map<br/>[Heatmap.tsx]"]
  node_prototype["Vanilla prototype<br/>[app.js]"]
  node_prototype_sos["Prototype SOS<br/>[sos.js]"]
  node_zones["Zone definitions<br/>[safety_zone.js]"]
  node_sensors["Prototype sensors<br/>[sensor.js]"]
  node_prototype_map["Prototype map<br/>[map.js]"]
end

subgraph group_api["Application API"]
  node_contacts["Emergency contacts<br/>[contactRoutes.ts]"]
  node_auth["Authentication<br/>[authRoutes.ts]"]
  node_guard["JWT authorization<br/>[authMiddleware.ts]"]
  node_sos_api["SOS event logging<br/>[sosRoutes.ts]"]
  node_api_server["REST and signaling<br/>[server.ts]"]
  node_store[("Relational database<br/>[schema.prisma]")]
end

subgraph group_monitoring["Incident monitoring"]
  node_admin["Admin dashboard<br/>[Admin.tsx]"]
  node_admin_api["Admin stats and logs<br/>[adminRoutes.ts]"]
  node_victim_stream["Victim media stream<br/>[useWebRTCStream.ts]"]
  node_admin_stream["Admin media receiver<br/>[useWebRTCAdmin.ts]"]
end

subgraph group_ai["Risk analysis"]
  node_ai_service["Risk scoring stub<br/>[main.py]"]
end

node_person(("Person at risk"))
node_emergency(("Emergency recipients"))
node_admin_user(("Monitoring admin"))
node_peer_media(("Direct peer media"))

node_person -->|"uses"| node_react
node_react -->|"routes to"| node_home
node_home -->|"uses"| node_voice
node_home -->|"uses"| node_fall
node_home -->|"uses"| node_location
node_home -->|"reads settings"| node_settings
node_voice -->|"reads settings"| node_settings
node_home -->|"renders"| node_map
node_person -->|"uses"| node_prototype
node_prototype -.->|"delegates SOS"| node_prototype_sos
node_prototype -.->|"uses sensors"| node_sensors
node_prototype -.->|"uses map"| node_prototype_map
node_prototype_map -.->|"uses zones"| node_zones
node_home -.->|"loads contacts"| node_contacts
node_home -.->|"posts event"| node_sos_api
node_home -.->|"opens SMS alerts"| node_emergency
node_react -.->|"submits credentials"| node_auth
node_api_server -->|"mounts route"| node_auth
node_api_server -->|"mounts route"| node_contacts
node_api_server -->|"mounts route"| node_sos_api
node_api_server -->|"mounts route"| node_admin_api
node_auth -->|"reads and writes"| node_store
node_contacts -->|"authenticates with"| node_guard
node_sos_api -->|"authenticates with"| node_guard
node_admin_api -->|"authenticates with"| node_guard
node_contacts -->|"reads and writes"| node_store
node_sos_api -->|"writes event"| node_store
node_admin_api -->|"reads stats and incidents"| node_store
node_admin_user -->|"views incidents"| node_admin
node_admin -.->|"loads stats and logs"| node_admin_api
node_home -->|"starts on SOS"| node_victim_stream
node_admin -->|"uses receiver"| node_admin_stream
node_victim_stream -->|"sends signaling"| node_api_server
node_api_server -->|"relays signaling"| node_admin_stream
node_victim_stream -->|"streams media"| node_peer_media
node_peer_media -->|"delivers media"| node_admin_stream
node_person -.->|"requests risk score"| node_ai_service

click node_react "https://github.com/vizzie8/safeguard/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/vizzie8/safeguard/blob/main/frontend/src/pages/Home.tsx"
click node_settings "https://github.com/vizzie8/safeguard/blob/main/frontend/src/context/SettingsContext.tsx"
click node_voice "https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useVoiceRecognition.ts"
click node_fall "https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useFallDetection.ts"
click node_location "https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useLocationTracking.ts"
click node_map "https://github.com/vizzie8/safeguard/blob/main/frontend/src/components/Heatmap.tsx"
click node_prototype "https://github.com/vizzie8/safeguard/blob/main/app.js"
click node_prototype_sos "https://github.com/vizzie8/safeguard/blob/main/sos.js"
click node_zones "https://github.com/vizzie8/safeguard/blob/main/safety_zone.js"
click node_sensors "https://github.com/vizzie8/safeguard/blob/main/sensor.js"
click node_prototype_map "https://github.com/vizzie8/safeguard/blob/main/map.js"
click node_contacts "https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/contactRoutes.ts"
click node_auth "https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/authRoutes.ts"
click node_guard "https://github.com/vizzie8/safeguard/blob/main/backend-node/src/middlewares/authMiddleware.ts"
click node_sos_api "https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/sosRoutes.ts"
click node_api_server "https://github.com/vizzie8/safeguard/blob/main/backend-node/src/server.ts"
click node_store "https://github.com/vizzie8/safeguard/blob/main/backend-node/prisma/schema.prisma"
click node_admin "https://github.com/vizzie8/safeguard/blob/main/frontend/src/pages/Admin.tsx"
click node_admin_api "https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/adminRoutes.ts"
click node_victim_stream "https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useWebRTCStream.ts"
click node_admin_stream "https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useWebRTCAdmin.ts"
click node_ai_service "https://github.com/vizzie8/safeguard/blob/main/backend-ai/main.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_react,node_home,node_settings,node_voice,node_fall,node_location,node_map,node_prototype,node_prototype_sos,node_zones,node_sensors,node_prototype_map toneBlue
class node_contacts,node_auth,node_guard,node_sos_api,node_api_server,node_store toneAmber
class node_admin,node_admin_api,node_victim_stream,node_admin_stream toneMint
class node_ai_service toneRose
class node_person,node_emergency,node_admin_user,node_peer_media toneIndigo
```

## Components

### Safety clients

- [React application](https://github.com/vizzie8/safeguard/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Safety dashboard](https://github.com/vizzie8/safeguard/blob/main/frontend/src/pages/Home.tsx): `frontend/src/pages/Home.tsx`
- [Safety settings](https://github.com/vizzie8/safeguard/blob/main/frontend/src/context/SettingsContext.tsx): `frontend/src/context/SettingsContext.tsx`
- [Voice detection](https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useVoiceRecognition.ts): `frontend/src/hooks/useVoiceRecognition.ts`
- [Impact detection](https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useFallDetection.ts): `frontend/src/hooks/useFallDetection.ts`
- [Location tracking](https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useLocationTracking.ts): `frontend/src/hooks/useLocationTracking.ts`
- [Risk-zone map](https://github.com/vizzie8/safeguard/blob/main/frontend/src/components/Heatmap.tsx): `frontend/src/components/Heatmap.tsx`
- [Vanilla prototype](https://github.com/vizzie8/safeguard/blob/main/app.js): `app.js`
- [Prototype SOS](https://github.com/vizzie8/safeguard/blob/main/sos.js): `sos.js`
- [Zone definitions](https://github.com/vizzie8/safeguard/blob/main/safety_zone.js): `safety_zone.js`
- [Prototype sensors](https://github.com/vizzie8/safeguard/blob/main/sensor.js): `sensor.js`
- [Prototype map](https://github.com/vizzie8/safeguard/blob/main/map.js): `map.js`

### Application API

- [Emergency contacts](https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/contactRoutes.ts): `backend-node/src/routes/contactRoutes.ts`
- [Authentication](https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/authRoutes.ts): `backend-node/src/routes/authRoutes.ts`
- [JWT authorization](https://github.com/vizzie8/safeguard/blob/main/backend-node/src/middlewares/authMiddleware.ts): `backend-node/src/middlewares/authMiddleware.ts`
- [SOS event logging](https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/sosRoutes.ts): `backend-node/src/routes/sosRoutes.ts`
- [REST and signaling](https://github.com/vizzie8/safeguard/blob/main/backend-node/src/server.ts): `backend-node/src/server.ts`
- [Relational database](https://github.com/vizzie8/safeguard/blob/main/backend-node/prisma/schema.prisma): `backend-node/prisma/schema.prisma`

### Incident monitoring

- [Admin dashboard](https://github.com/vizzie8/safeguard/blob/main/frontend/src/pages/Admin.tsx): `frontend/src/pages/Admin.tsx`
- [Admin stats and logs](https://github.com/vizzie8/safeguard/blob/main/backend-node/src/routes/adminRoutes.ts): `backend-node/src/routes/adminRoutes.ts`
- [Victim media stream](https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useWebRTCStream.ts): `frontend/src/hooks/useWebRTCStream.ts`
- [Admin media receiver](https://github.com/vizzie8/safeguard/blob/main/frontend/src/hooks/useWebRTCAdmin.ts): `frontend/src/hooks/useWebRTCAdmin.ts`

### Risk analysis

- [Risk scoring stub](https://github.com/vizzie8/safeguard/blob/main/backend-ai/main.py): `backend-ai/main.py`

### Other components

- **Person at risk**
- **Emergency recipients**
- **Monitoring admin**
- **Direct peer media**

## Connections

- Person at risk → React application: uses (evidence: `README.md`)
- React application → Safety dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Safety dashboard → Voice detection: uses (evidence: `frontend/src/pages/Home.tsx`)
- Safety dashboard → Impact detection: uses (evidence: `frontend/src/pages/Home.tsx`)
- Safety dashboard → Location tracking: uses (evidence: `frontend/src/pages/Home.tsx`)
- Safety dashboard → Safety settings: reads settings (evidence: `frontend/src/pages/Home.tsx`)
- Voice detection → Safety settings: reads settings (evidence: `frontend/src/hooks/useVoiceRecognition.ts`)
- Safety dashboard → Risk-zone map: renders
- Person at risk → Vanilla prototype: uses (evidence: `README.md`)
- Vanilla prototype → Prototype SOS: delegates SOS
- Vanilla prototype → Prototype sensors: uses sensors
- Vanilla prototype → Prototype map: uses map
- Prototype map → Zone definitions: uses zones
- Safety dashboard → Emergency contacts: loads contacts
- Safety dashboard → SOS event logging: posts event (evidence: `README.md`)
- Safety dashboard → Emergency recipients: opens SMS alerts (evidence: `README.md`)
- React application → Authentication: submits credentials
- REST and signaling → Authentication: mounts route (evidence: `backend-node/src/server.ts`)
- REST and signaling → Emergency contacts: mounts route (evidence: `backend-node/src/server.ts`)
- REST and signaling → SOS event logging: mounts route (evidence: `backend-node/src/server.ts`)
- REST and signaling → Admin stats and logs: mounts route (evidence: `backend-node/src/server.ts`)
- Authentication → Relational database: reads and writes (evidence: `backend-node/src/routes/authRoutes.ts`)
- Emergency contacts → JWT authorization: authenticates with (evidence: `backend-node/src/routes/contactRoutes.ts`)
- SOS event logging → JWT authorization: authenticates with (evidence: `backend-node/src/routes/sosRoutes.ts`)
- Admin stats and logs → JWT authorization: authenticates with (evidence: `backend-node/src/routes/adminRoutes.ts`)
- Emergency contacts → Relational database: reads and writes (evidence: `backend-node/src/routes/contactRoutes.ts`)
- SOS event logging → Relational database: writes event (evidence: `backend-node/src/routes/sosRoutes.ts`)
- Admin stats and logs → Relational database: reads stats and incidents (evidence: `backend-node/src/routes/adminRoutes.ts`)
- Monitoring admin → Admin dashboard: views incidents (evidence: `README.md`)
- Admin dashboard → Admin stats and logs: loads stats and logs
- Safety dashboard → Victim media stream: starts on SOS (evidence: `frontend/src/pages/Home.tsx`)
- Admin dashboard → Admin media receiver: uses receiver (evidence: `frontend/src/pages/Admin.tsx`)
- Victim media stream → REST and signaling: sends signaling (evidence: `frontend/src/hooks/useWebRTCStream.ts`)
- REST and signaling → Admin media receiver: relays signaling (evidence: `backend-node/src/server.ts`)
- Victim media stream → Direct peer media: streams media (evidence: `README.md`)
- Direct peer media → Admin media receiver: delivers media (evidence: `README.md`)
- Person at risk → Risk scoring stub: requests risk score
