# ngtanvan/ml_aiot-elderly-fall-detection-system architecture

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

- Interactive diagram: https://gitdiagram.com/ngtanvan/ml_aiot-elderly-fall-detection-system
- Repository: https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system

## Overview

An Toàn AI is a real-time fall and suspected-stroke monitoring system with a React dashboard, FastAPI backend, camera-based detection, alert history, and Telegram notifications. The documented primary workflow is camera video → fall classification and timed confirmation → incident evidence/history and Telegram alert → dashboard monitoring. Authentication, account recovery, and bot linking form a separate user-management branch. The sampled detector and application bootstrap support the timing and service boundaries; video, camera, notifier, bot-listener, and dashboard internals were not sampled, so their detailed wiring is not asserted.

Main entry points: [`fall-detection-system/backend/app/api/auth.py`](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/api/auth.py) (Auth API), [`fall-detection-system/backend/app/main.py`](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/main.py) (FastAPI application), [`fall-detection-system/backend/app/services/notifier.py`](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/services/notifier.py) (Alert notifier), [`fall-detection-system/frontend/src/App.jsx`](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/App.jsx) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monitoring["Monitoring and alerts"]
  node_video_api["Video API<br/>[video.py]"]
  node_camera_service["Camera service<br/>[camera.py]"]
  node_detector["Fall detector<br/>[detector.py]"]
  node_notifier["Alert notifier<br/>[notifier.py]"]
  node_alert_images[("Alert evidence")]
  node_socket_manager["Socket manager<br/>[socket_manager.py]"]
end

subgraph group_web["Web application"]
  node_history_page["Alert history<br/>[HistoryPage.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_live_stream["Live stream<br/>[LiveStream.jsx]"]
  node_alert_popup["Alert popup<br/>[AlertPopup.jsx]"]
  node_frontend_app["App routes<br/>[App.jsx]"]
  node_auth_service["Auth client<br/>[authService.js]"]
  node_landing["Sign-in and recovery<br/>[LandingPage.jsx]"]
end

subgraph group_identity["Identity and persistence"]
  node_backend_app["FastAPI application<br/>[main.py]"]
  node_auth_api["Auth API<br/>[auth.py]"]
  node_security["Token and password security<br/>[security.py]"]
  node_database[("SQLite data<br/>[database.py]")]
end

subgraph group_messaging["Telegram integration"]
  node_bot_listener["Telegram bot listener<br/>[bot_listener.py]"]
end

node_caregiver(("Caregiver"))
node_camera(("Surveillance camera"))
node_telegram(("Telegram"))

node_caregiver -->|"uses"| node_frontend_app
node_frontend_app -->|"routes to"| node_landing
node_frontend_app -->|"routes to"| node_dashboard
node_frontend_app -->|"routes to"| node_history_page
node_landing -->|"calls"| node_auth_service
node_auth_service -->|"requests"| node_auth_api
node_backend_app -->|"registers"| node_auth_api
node_backend_app -->|"registers"| node_video_api
node_backend_app -->|"mounts"| node_socket_manager
node_auth_api -->|"reads and writes"| node_database
node_auth_api -->|"verifies and hashes"| node_security
node_camera -.->|"provides video"| node_camera_service
node_video_api -.->|"uses"| node_camera_service
node_camera_service -.->|"provides frames"| node_detector
node_detector -.->|"triggers alert"| node_notifier
node_notifier -.->|"stores evidence"| node_alert_images
node_notifier -.->|"records alert"| node_database
node_notifier -.->|"dispatches alert"| node_bot_listener
node_bot_listener -.->|"sends alert"| node_telegram
node_auth_api -.->|"sends recovery OTP"| node_telegram
node_history_page -.->|"requests history"| node_backend_app
node_live_stream -.->|"requests stream"| node_backend_app
node_alert_popup -.->|"receives events"| node_socket_manager
node_dashboard -.->|"shows stream"| node_live_stream

click node_video_api "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/api/video.py"
click node_camera_service "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/services/camera.py"
click node_detector "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/services/detector.py"
click node_notifier "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/services/notifier.py"
click node_alert_images "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/tree/main/fall-detection-system/backend/alert_images"
click node_history_page "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/pages/HistoryPage.jsx"
click node_dashboard "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/pages/Dashboard.jsx"
click node_live_stream "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/components/VideoPlayer/LiveStream.jsx"
click node_alert_popup "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/components/Layout/AlertPopup.jsx"
click node_frontend_app "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/App.jsx"
click node_auth_service "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/services/authService.js"
click node_landing "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/pages/LandingPage.jsx"
click node_backend_app "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/main.py"
click node_auth_api "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/api/auth.py"
click node_security "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/core/security.py"
click node_database "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/core/database.py"
click node_socket_manager "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/core/socket_manager.py"
click node_bot_listener "https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/bot_listener.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_video_api,node_camera_service,node_detector,node_notifier,node_alert_images,node_socket_manager toneBlue
class node_history_page,node_dashboard,node_live_stream,node_alert_popup,node_frontend_app,node_auth_service,node_landing toneAmber
class node_backend_app,node_auth_api,node_security,node_database toneMint
class node_bot_listener toneRose
class node_caregiver,node_camera,node_telegram toneIndigo
```

## Components

### Monitoring and alerts

- [Video API](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/api/video.py): `fall-detection-system/backend/app/api/video.py`
- [Camera service](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/services/camera.py): `fall-detection-system/backend/app/services/camera.py`
- [Fall detector](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/services/detector.py): `fall-detection-system/backend/app/services/detector.py`
- [Alert notifier](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/services/notifier.py): `fall-detection-system/backend/app/services/notifier.py`
- [Alert evidence](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/tree/main/fall-detection-system/backend/alert_images): `fall-detection-system/backend/alert_images`
- [Socket manager](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/core/socket_manager.py): `fall-detection-system/backend/app/core/socket_manager.py`

### Web application

- [Alert history](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/pages/HistoryPage.jsx): `fall-detection-system/frontend/src/pages/HistoryPage.jsx`
- [Dashboard](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/pages/Dashboard.jsx): `fall-detection-system/frontend/src/pages/Dashboard.jsx`
- [Live stream](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/components/VideoPlayer/LiveStream.jsx): `fall-detection-system/frontend/src/components/VideoPlayer/LiveStream.jsx`
- [Alert popup](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/components/Layout/AlertPopup.jsx): `fall-detection-system/frontend/src/components/Layout/AlertPopup.jsx`
- [App routes](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/App.jsx): `fall-detection-system/frontend/src/App.jsx`
- [Auth client](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/services/authService.js): `fall-detection-system/frontend/src/services/authService.js`
- [Sign-in and recovery](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/frontend/src/pages/LandingPage.jsx): `fall-detection-system/frontend/src/pages/LandingPage.jsx`

### Identity and persistence

- [FastAPI application](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/main.py): `fall-detection-system/backend/app/main.py`
- [Auth API](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/api/auth.py): `fall-detection-system/backend/app/api/auth.py`
- [Token and password security](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/core/security.py): `fall-detection-system/backend/app/core/security.py`
- [SQLite data](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/app/core/database.py): `fall-detection-system/backend/app/core/database.py`

### Telegram integration

- [Telegram bot listener](https://github.com/ngtanvan/ml_aiot-elderly-fall-detection-system/blob/main/fall-detection-system/backend/bot_listener.py): `fall-detection-system/backend/bot_listener.py`

### Other components

- **Caregiver**
- **Surveillance camera**
- **Telegram**

## Connections

- Caregiver → App routes: uses
- App routes → Sign-in and recovery: routes to
- App routes → Dashboard: routes to
- App routes → Alert history: routes to
- Sign-in and recovery → Auth client: calls
- Auth client → Auth API: requests
- FastAPI application → Auth API: registers
- FastAPI application → Video API: registers
- FastAPI application → Socket manager: mounts
- Auth API → SQLite data: reads and writes
- Auth API → Token and password security: verifies and hashes
- Surveillance camera → Camera service: provides video
- Video API → Camera service: uses
- Camera service → Fall detector: provides frames
- Fall detector → Alert notifier: triggers alert
- Alert notifier → Alert evidence: stores evidence
- Alert notifier → SQLite data: records alert
- Alert notifier → Telegram bot listener: dispatches alert
- Telegram bot listener → Telegram: sends alert
- Auth API → Telegram: sends recovery OTP
- Alert history → FastAPI application: requests history
- Live stream → FastAPI application: requests stream
- Alert popup → Socket manager: receives events
- Dashboard → Live stream: shows stream