# dvj1/safepath architecture

> Architecture diagram of the GitHub repository dvj1/safepath, 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/dvj1/safepath
- Repository: https://github.com/dvj1/safepath

## Overview

SafePath is a Flutter smart-stick companion and caregiver safety app. Users monitor stick and surface hazards with voice guidance, trigger or cancel fall alarms, and send GPS-backed SOS alerts; caregivers monitor telemetry, respond through an emergency lifecycle, and review history and user details. The README documents the Dart subsystem roles and capabilities, but sampled source excerpts cover only platform runners, not Dart runtime calls; edges below therefore represent documented relationships, not independently verified call sites.

Main entry points: [`lib/services/emergency_service.dart`](https://github.com/dvj1/safepath/blob/main/lib/services/emergency_service.dart) (Emergency Coordination), [`lib/screens/caregiver_dashboard_screen.dart`](https://github.com/dvj1/safepath/blob/main/lib/screens/caregiver_dashboard_screen.dart) (Caregiver Dashboard), [`lib/screens/user_dashboard_screen.dart`](https://github.com/dvj1/safepath/blob/main/lib/screens/user_dashboard_screen.dart) (User Dashboard), [`lib/main.dart`](https://github.com/dvj1/safepath/blob/main/lib/main.dart) (Flutter App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User Experience"]
  node_app["Flutter App<br/>[main.dart]"]
  node_userdash["User Dashboard"]
  node_map["Live Map<br/>[live_map_view.dart]"]
  node_settings["Hardware Settings"]
end

subgraph group_safety["Safety Workflows"]
  node_sos["SOS Control"]
  node_fall["Fall Alarm"]
  node_emergency["Emergency Coordination"]
  node_event["Emergency Event"]
end

subgraph group_services["Device and App Services"]
  node_sensors["Stick Telemetry"]
  node_hardware["Stick Integration"]
  node_speech["Voice and Haptics"]
  node_location["Phone Location"]
  node_backend["Backend Repository"]
  node_notifications["Emergency Notifications"]
  node_storage[("Local Storage")]
  node_config["ESP32 Configuration<br/>[esp32_config.dart]"]
end

subgraph group_care["Caregiver Response"]
  node_caregiverdash["Caregiver Dashboard"]
  node_history["Emergency History"]
  node_details["Emergency Details"]
  node_contacts["Contacts and Profile"]
  node_profile["User Profile<br/>[user_profile.dart]"]
end

node_user(("Stick User"))
node_caregiver(("Caregiver"))
node_esp32{{"ESP32 Stick"}}

node_user -->|"uses"| node_app
node_caregiver -->|"uses"| node_app
node_app -->|"presents"| node_userdash
node_app -->|"presents"| node_caregiverdash
node_userdash -->|"shows telemetry"| node_sensors
node_hardware -->|"reads sensors"| node_esp32
node_hardware -->|"produces readings"| node_sensors
node_userdash -->|"announces hazards"| node_speech
node_userdash -->|"offers SOS"| node_sos
node_fall -->|"triggers after countdown"| node_emergency
node_sos -->|"triggers"| node_emergency
node_emergency -->|"gets coordinates"| node_location
node_emergency -->|"broadcasts alert"| node_backend
node_emergency -->|"sends notification"| node_notifications
node_emergency -->|"records event"| node_event
node_caregiverdash -->|"shows telemetry"| node_sensors
node_caregiverdash -->|"shows location"| node_map
node_map -->|"displays position"| node_location
node_caregiverdash -->|"opens logs"| node_history
node_history -->|"opens event"| node_details
node_details -->|"shows lifecycle"| node_event
node_caregiverdash -->|"views user details"| node_contacts
node_contacts -->|"shows profile"| node_profile
node_history -->|"reads past logs"| node_storage
node_settings -->|"edits configuration"| node_config
node_settings -->|"configures device"| node_hardware
node_backend -.->|"uses local persistence"| node_storage

click node_app "https://github.com/dvj1/safepath/blob/main/lib/main.dart"
click node_userdash "https://github.com/dvj1/safepath/blob/main/lib/screens/user_dashboard_screen.dart"
click node_caregiverdash "https://github.com/dvj1/safepath/blob/main/lib/screens/caregiver_dashboard_screen.dart"
click node_sos "https://github.com/dvj1/safepath/blob/main/lib/widgets/sos_emergency_button.dart"
click node_fall "https://github.com/dvj1/safepath/blob/main/lib/services/emergency_service.dart"
click node_emergency "https://github.com/dvj1/safepath/blob/main/lib/services/emergency_service.dart"
click node_event "https://github.com/dvj1/safepath/blob/main/lib/models/emergency_event.dart"
click node_sensors "https://github.com/dvj1/safepath/blob/main/lib/models/stick_sensor_data.dart"
click node_hardware "https://github.com/dvj1/safepath/blob/main/lib/services/hardware_service.dart"
click node_speech "https://github.com/dvj1/safepath/blob/main/lib/services/tts_audio_service.dart"
click node_location "https://github.com/dvj1/safepath/blob/main/lib/services/location_service.dart"
click node_map "https://github.com/dvj1/safepath/blob/main/lib/widgets/live_map_view.dart"
click node_backend "https://github.com/dvj1/safepath/blob/main/lib/services/backend_service.dart"
click node_notifications "https://github.com/dvj1/safepath/blob/main/lib/services/notification_service.dart"
click node_storage "https://github.com/dvj1/safepath/blob/main/lib/services/storage_service.dart"
click node_history "https://github.com/dvj1/safepath/blob/main/lib/screens/emergency_history_screen.dart"
click node_details "https://github.com/dvj1/safepath/blob/main/lib/screens/emergency_details_screen.dart"
click node_contacts "https://github.com/dvj1/safepath/blob/main/lib/screens/contacts_screen.dart"
click node_profile "https://github.com/dvj1/safepath/blob/main/lib/models/user_profile.dart"
click node_settings "https://github.com/dvj1/safepath/blob/main/lib/screens/hardware_settings_screen.dart"
click node_config "https://github.com/dvj1/safepath/blob/main/lib/models/esp32_config.dart"

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_app,node_userdash,node_map,node_settings,node_user toneBlue
class node_sos,node_fall,node_emergency,node_event toneAmber
class node_sensors,node_hardware,node_speech,node_location,node_backend,node_notifications,node_storage,node_config toneMint
class node_caregiverdash,node_history,node_details,node_contacts,node_profile toneRose
class node_caregiver,node_esp32 toneIndigo
```

## Components

### User Experience

- [Flutter App](https://github.com/dvj1/safepath/blob/main/lib/main.dart): `lib/main.dart`
- [User Dashboard](https://github.com/dvj1/safepath/blob/main/lib/screens/user_dashboard_screen.dart): `lib/screens/user_dashboard_screen.dart`
- [Live Map](https://github.com/dvj1/safepath/blob/main/lib/widgets/live_map_view.dart): `lib/widgets/live_map_view.dart`
- [Hardware Settings](https://github.com/dvj1/safepath/blob/main/lib/screens/hardware_settings_screen.dart): `lib/screens/hardware_settings_screen.dart`

### Safety Workflows

- [SOS Control](https://github.com/dvj1/safepath/blob/main/lib/widgets/sos_emergency_button.dart): `lib/widgets/sos_emergency_button.dart`
- [Fall Alarm](https://github.com/dvj1/safepath/blob/main/lib/services/emergency_service.dart): `lib/services/emergency_service.dart`
- [Emergency Coordination](https://github.com/dvj1/safepath/blob/main/lib/services/emergency_service.dart): `lib/services/emergency_service.dart`
- [Emergency Event](https://github.com/dvj1/safepath/blob/main/lib/models/emergency_event.dart): `lib/models/emergency_event.dart`

### Device and App Services

- [Stick Telemetry](https://github.com/dvj1/safepath/blob/main/lib/models/stick_sensor_data.dart): `lib/models/stick_sensor_data.dart`
- [Stick Integration](https://github.com/dvj1/safepath/blob/main/lib/services/hardware_service.dart): `lib/services/hardware_service.dart`
- [Voice and Haptics](https://github.com/dvj1/safepath/blob/main/lib/services/tts_audio_service.dart): `lib/services/tts_audio_service.dart`
- [Phone Location](https://github.com/dvj1/safepath/blob/main/lib/services/location_service.dart): `lib/services/location_service.dart`
- [Backend Repository](https://github.com/dvj1/safepath/blob/main/lib/services/backend_service.dart): `lib/services/backend_service.dart`
- [Emergency Notifications](https://github.com/dvj1/safepath/blob/main/lib/services/notification_service.dart): `lib/services/notification_service.dart`
- [Local Storage](https://github.com/dvj1/safepath/blob/main/lib/services/storage_service.dart): `lib/services/storage_service.dart`
- [ESP32 Configuration](https://github.com/dvj1/safepath/blob/main/lib/models/esp32_config.dart): `lib/models/esp32_config.dart`

### Caregiver Response

- [Caregiver Dashboard](https://github.com/dvj1/safepath/blob/main/lib/screens/caregiver_dashboard_screen.dart): `lib/screens/caregiver_dashboard_screen.dart`
- [Emergency History](https://github.com/dvj1/safepath/blob/main/lib/screens/emergency_history_screen.dart): `lib/screens/emergency_history_screen.dart`
- [Emergency Details](https://github.com/dvj1/safepath/blob/main/lib/screens/emergency_details_screen.dart): `lib/screens/emergency_details_screen.dart`
- [Contacts and Profile](https://github.com/dvj1/safepath/blob/main/lib/screens/contacts_screen.dart): `lib/screens/contacts_screen.dart`
- [User Profile](https://github.com/dvj1/safepath/blob/main/lib/models/user_profile.dart): `lib/models/user_profile.dart`

### Other components

- **Stick User**
- **Caregiver**
- **ESP32 Stick**

## Connections

- Stick User → Flutter App: uses (evidence: `README.md`)
- Caregiver → Flutter App: uses (evidence: `README.md`)
- Flutter App → User Dashboard: presents (evidence: `README.md`)
- Flutter App → Caregiver Dashboard: presents (evidence: `README.md`)
- User Dashboard → Stick Telemetry: shows telemetry (evidence: `README.md`)
- Stick Integration → ESP32 Stick: reads sensors (evidence: `README.md`)
- Stick Integration → Stick Telemetry: produces readings (evidence: `README.md`)
- User Dashboard → Voice and Haptics: announces hazards (evidence: `README.md`)
- User Dashboard → SOS Control: offers SOS (evidence: `README.md`)
- Fall Alarm → Emergency Coordination: triggers after countdown (evidence: `README.md`)
- SOS Control → Emergency Coordination: triggers (evidence: `README.md`)
- Emergency Coordination → Phone Location: gets coordinates (evidence: `README.md`)
- Emergency Coordination → Backend Repository: broadcasts alert (evidence: `README.md`)
- Emergency Coordination → Emergency Notifications: sends notification (evidence: `README.md`)
- Emergency Coordination → Emergency Event: records event (evidence: `README.md`)
- Caregiver Dashboard → Stick Telemetry: shows telemetry (evidence: `README.md`)
- Caregiver Dashboard → Live Map: shows location (evidence: `README.md`)
- Live Map → Phone Location: displays position (evidence: `README.md`)
- Caregiver Dashboard → Emergency History: opens logs (evidence: `README.md`)
- Emergency History → Emergency Details: opens event (evidence: `README.md`)
- Emergency Details → Emergency Event: shows lifecycle (evidence: `README.md`)
- Caregiver Dashboard → Contacts and Profile: views user details (evidence: `README.md`)
- Contacts and Profile → User Profile: shows profile (evidence: `README.md`)
- Emergency History → Local Storage: reads past logs (evidence: `README.md`)
- Hardware Settings → ESP32 Configuration: edits configuration (evidence: `README.md`)
- Hardware Settings → Stick Integration: configures device (evidence: `README.md`)
- Backend Repository → Local Storage: uses local persistence
