# awac8989/safe_solo architecture

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

- Interactive diagram: https://gitdiagram.com/awac8989/safe_solo
- Repository: https://github.com/awac8989/safe_solo

## Overview

SafeSolo is a cross-device emergency detection and rescue-coordination system: mobile and watch users generate safety signals or request help; the backend evaluates check-ins and incidents, coordinates responders and notifications, and exposes live operations to an admin portal. The graph preserves documented capabilities whose implementation is not in the sampled excerpts, but omits uncertain wiring for those features. Mobile and watch application source is absent from the supplied tree, so those initiating devices are represented as external actors.

Main entry points: [`backend/src/routes/watchRoutes.js`](https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/watchRoutes.js) (Watch API), [`backend/src/workers/deadmanWorker.js`](https://github.com/awac8989/safe_solo/blob/main/backend/src/workers/deadmanWorker.js) (Check-in monitor), [`backend/src/services/adminPortalService.js`](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/adminPortalService.js) (Admin services), [`backend/src/services/sosService.js`](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/sosService.js) (SOS coordination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["User Edge"]
  node_mobile_app["SafeSolo mobile"]
  node_galaxy_watch["Galaxy Watch"]
  node_watch_api["Watch API<br/>[watchRoutes.js]"]
  node_socket_server["Realtime sockets<br/>[socketServer.js]"]
  node_api_entry["API entry<br/>[index.js]"]
end

subgraph group_response["Emergency Response"]
  node_community_api["Community routes<br/>[communityRoutes.js]"]
  node_hazard_service["Hazard services<br/>[hazardService.js]"]
  node_emergency_api["Emergency routes<br/>[emergencyRoutes.js]"]
  node_sos_service["SOS coordination<br/>[sosService.js]"]
  node_dispatch_channels["Alert channels<br/>[smsService.js]"]
end

subgraph group_safety["Safety Services"]
  node_deadman_worker["Check-in monitor<br/>[deadmanWorker.js]"]
  node_user_controller["User controller<br/>[userController.js]"]
  node_auth_service["Identity service<br/>[authService.js]"]
  node_chat_api["Chat routes<br/>[chatRoutes.js]"]
  node_chat_controller["Chat controller<br/>[chatController.js]"]
  node_chat_service["Chat service<br/>[chatService.js]"]
  node_medical_service["Medical profiles<br/>[medicalService.js]"]
  node_journey_service["Live journeys<br/>[journeyService.js]"]
  node_mongodb[("MongoDB<br/>[database.js]")]
end

subgraph group_operations["Dispatch Operations"]
  node_admin_portal["Admin portal<br/>[index.tsx]"]
  node_admin_api["Admin routes"]
  node_admin_controller["Admin controller"]
  node_admin_service["Admin services"]
  node_incident_data[("Incident records<br/>[RescueIncident.js]")]
end

node_mobile_user(("Mobile user"))
node_watch_user(("Watch user"))
node_admin_user(("Dispatcher"))
node_telegram["Telegram"]
node_external_channels["SMS and voice gateways"]

node_mobile_user -->|"uses"| node_mobile_app
node_watch_user -->|"uses"| node_galaxy_watch
node_admin_user -->|"operates"| node_admin_portal
node_galaxy_watch -->|"sends telemetry"| node_watch_api
node_watch_api -->|"emits events"| node_socket_server
node_watch_api -->|"queues commands"| node_galaxy_watch
node_mobile_app -->|"calls API"| node_api_entry
node_mobile_app -->|"pairs and polls"| node_watch_api
node_mobile_app -->|"requests rescue"| node_emergency_api
node_mobile_app -->|"reports hazards"| node_community_api
node_admin_portal -->|"calls API"| node_admin_api
node_admin_api -->|"dispatches"| node_admin_controller
node_admin_controller -->|"calls"| node_admin_service
node_admin_service -->|"reads and writes"| node_incident_data
node_community_api -->|"calls"| node_hazard_service
node_emergency_api -->|"initiates SOS"| node_sos_service
node_deadman_worker -->|"reads check-ins"| node_mongodb
node_deadman_worker -->|"triggers SOS"| node_sos_service
node_deadman_worker -.->|"sends reminders"| node_telegram
node_sos_service -->|"dispatches alerts"| node_dispatch_channels
node_dispatch_channels -.->|"sends notifications"| node_external_channels
node_admin_service -.->|"coordinates dispatch"| node_external_channels
node_chat_api -->|"dispatches"| node_chat_controller
node_chat_controller -->|"calls"| node_chat_service
node_chat_service -->|"stores messages"| node_mongodb
node_mobile_app -->|"authenticates"| node_auth_service
node_mobile_app -->|"manages check-ins"| node_user_controller
node_mobile_app -->|"manages medical data"| node_medical_service
node_mobile_app -->|"shares journeys"| node_journey_service

click node_watch_api "https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/watchRoutes.js"
click node_socket_server "https://github.com/awac8989/safe_solo/blob/main/backend/src/sockets/socketServer.js"
click node_api_entry "https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/index.js"
click node_admin_portal "https://github.com/awac8989/safe_solo/blob/main/web-admin/src/routes/index.tsx"
click node_admin_api "https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/adminPortalRoutes.js"
click node_admin_controller "https://github.com/awac8989/safe_solo/blob/main/backend/src/controllers/adminPortalController.js"
click node_admin_service "https://github.com/awac8989/safe_solo/blob/main/backend/src/services/adminPortalService.js"
click node_incident_data "https://github.com/awac8989/safe_solo/blob/main/backend/src/models/RescueIncident.js"
click node_community_api "https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/communityRoutes.js"
click node_hazard_service "https://github.com/awac8989/safe_solo/blob/main/backend/src/services/hazardService.js"
click node_emergency_api "https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/emergencyRoutes.js"
click node_sos_service "https://github.com/awac8989/safe_solo/blob/main/backend/src/services/sosService.js"
click node_dispatch_channels "https://github.com/awac8989/safe_solo/blob/main/backend/src/services/smsService.js"
click node_deadman_worker "https://github.com/awac8989/safe_solo/blob/main/backend/src/workers/deadmanWorker.js"
click node_user_controller "https://github.com/awac8989/safe_solo/blob/main/backend/src/controllers/userController.js"
click node_auth_service "https://github.com/awac8989/safe_solo/blob/main/backend/src/services/authService.js"
click node_chat_api "https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/chatRoutes.js"
click node_chat_controller "https://github.com/awac8989/safe_solo/blob/main/backend/src/controllers/chatController.js"
click node_chat_service "https://github.com/awac8989/safe_solo/blob/main/backend/src/services/chatService.js"
click node_medical_service "https://github.com/awac8989/safe_solo/blob/main/backend/src/services/medicalService.js"
click node_journey_service "https://github.com/awac8989/safe_solo/blob/main/backend/src/services/journeyService.js"
click node_mongodb "https://github.com/awac8989/safe_solo/blob/main/backend/src/config/database.js"

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_app,node_galaxy_watch,node_watch_api,node_socket_server,node_api_entry,node_mobile_user,node_watch_user toneBlue
class node_community_api,node_hazard_service,node_emergency_api,node_sos_service,node_dispatch_channels toneAmber
class node_deadman_worker,node_user_controller,node_auth_service,node_chat_api,node_chat_controller,node_chat_service,node_medical_service,node_journey_service,node_mongodb toneMint
class node_admin_portal,node_admin_api,node_admin_controller,node_admin_service,node_incident_data toneRose
class node_admin_user,node_telegram,node_external_channels toneIndigo
```

## Components

### User Edge

- **SafeSolo mobile**
- **Galaxy Watch**
- [Watch API](https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/watchRoutes.js): `backend/src/routes/watchRoutes.js`
- [Realtime sockets](https://github.com/awac8989/safe_solo/blob/main/backend/src/sockets/socketServer.js): `backend/src/sockets/socketServer.js`
- [API entry](https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/index.js): `backend/src/routes/index.js`

### Emergency Response

- [Community routes](https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/communityRoutes.js): `backend/src/routes/communityRoutes.js`
- [Hazard services](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/hazardService.js): `backend/src/services/hazardService.js`
- [Emergency routes](https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/emergencyRoutes.js): `backend/src/routes/emergencyRoutes.js`
- [SOS coordination](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/sosService.js): `backend/src/services/sosService.js`
- [Alert channels](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/smsService.js): `backend/src/services/smsService.js`

### Safety Services

- [Check-in monitor](https://github.com/awac8989/safe_solo/blob/main/backend/src/workers/deadmanWorker.js): `backend/src/workers/deadmanWorker.js`
- [User controller](https://github.com/awac8989/safe_solo/blob/main/backend/src/controllers/userController.js): `backend/src/controllers/userController.js`
- [Identity service](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/authService.js): `backend/src/services/authService.js`
- [Chat routes](https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/chatRoutes.js): `backend/src/routes/chatRoutes.js`
- [Chat controller](https://github.com/awac8989/safe_solo/blob/main/backend/src/controllers/chatController.js): `backend/src/controllers/chatController.js`
- [Chat service](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/chatService.js): `backend/src/services/chatService.js`
- [Medical profiles](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/medicalService.js): `backend/src/services/medicalService.js`
- [Live journeys](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/journeyService.js): `backend/src/services/journeyService.js`
- [MongoDB](https://github.com/awac8989/safe_solo/blob/main/backend/src/config/database.js): `backend/src/config/database.js`

### Dispatch Operations

- [Admin portal](https://github.com/awac8989/safe_solo/blob/main/web-admin/src/routes/index.tsx): `web-admin/src/routes/index.tsx`
- [Admin routes](https://github.com/awac8989/safe_solo/blob/main/backend/src/routes/adminPortalRoutes.js): `backend/src/routes/adminPortalRoutes.js`
- [Admin controller](https://github.com/awac8989/safe_solo/blob/main/backend/src/controllers/adminPortalController.js): `backend/src/controllers/adminPortalController.js`
- [Admin services](https://github.com/awac8989/safe_solo/blob/main/backend/src/services/adminPortalService.js): `backend/src/services/adminPortalService.js`
- [Incident records](https://github.com/awac8989/safe_solo/blob/main/backend/src/models/RescueIncident.js): `backend/src/models/RescueIncident.js`

### Other components

- **Mobile user**
- **Watch user**
- **Dispatcher**
- **Telegram**
- **SMS and voice gateways**

## Connections

- Mobile user → SafeSolo mobile: uses
- Watch user → Galaxy Watch: uses
- Dispatcher → Admin portal: operates
- Galaxy Watch → Watch API: sends telemetry
- Watch API → Realtime sockets: emits events
- Watch API → Galaxy Watch: queues commands
- SafeSolo mobile → API entry: calls API
- SafeSolo mobile → Watch API: pairs and polls
- SafeSolo mobile → Emergency routes: requests rescue
- SafeSolo mobile → Community routes: reports hazards
- Admin portal → Admin routes: calls API
- Admin routes → Admin controller: dispatches
- Admin controller → Admin services: calls
- Admin services → Incident records: reads and writes
- Community routes → Hazard services: calls
- Emergency routes → SOS coordination: initiates SOS
- Check-in monitor → MongoDB: reads check-ins
- Check-in monitor → SOS coordination: triggers SOS
- Check-in monitor → Telegram: sends reminders
- SOS coordination → Alert channels: dispatches alerts
- Alert channels → SMS and voice gateways: sends notifications
- Admin services → SMS and voice gateways: coordinates dispatch
- Chat routes → Chat controller: dispatches
- Chat controller → Chat service: calls
- Chat service → MongoDB: stores messages
- SafeSolo mobile → Identity service: authenticates
- SafeSolo mobile → User controller: manages check-ins
- SafeSolo mobile → Medical profiles: manages medical data
- SafeSolo mobile → Live journeys: shares journeys