# joysjohney/driver-drowsiness-detection architecture

> Architecture diagram of the GitHub repository joysjohney/driver-drowsiness-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joysjohney/driver-drowsiness-detection
- Repository: https://github.com/joysjohney/driver-drowsiness-detection

## Overview

This is a **local, offline-capable, full-stack monolith** (single Flask app + static frontend) that performs **real-time driver drowsiness detection** from a **webcam feed** using **MediaPipe Face Mesh + OpenCV**, computes **EAR/MAR**, derives a **drowsiness score**, and triggers **audio/visual alerts** plus a **dashboard** (Chart.js timeline, stats, admin/user pages).

- The **real-time video processing loop** (camera → CV pipeline → score/alerts)
- The **UI dashboard** (live feed + metrics + timeline)
- The **Flask server** roles: serving pages/static assets, exposing endpoints, orchestrating detector, auth, and persistence
- The **local persistence** (SQLite DB files)
- Any **separation of concerns** inside backend utils (eye tracking, yawn detection, alert manager)

From the tree:

##### Backend (Python/Flask)
- `backend/app.py`
Likely the **Flask entrypoint**: routes for pages/APIs, camera capture, streaming frames, sending metrics to frontend.
- `backend/drowsiness_detector.py`
**Core detection engine** coordinating face mesh, EAR/MAR, scoring, state machine (Normal/Warning/Alert).
- `backend/utils/eye_tracker.py`
Computes **Eye Aspect Ratio** + blink/closure tracking thresholds.
- `backend/utils/yawn_detector.py`
Computes **Mouth Aspect Ratio** + yawn detection.
- `backend/utils/alert_manager.py`
**Alert policy** (cooldown, escalation) and “when to alert”.
- `backend/auth.py`
Authentication/authorization logic for login/register/admin flows.
- `backend/database.py` + `backend/users.db` + `backend/driver_data.db`
**SQLite persistence**. Likely users table + driver sessions/events/timeline data.

##### Frontend (static HTML/CSS/JS)
- Multiple HTML pages: `login.html`, `register.html`, `driver.html`, `admin.html`, etc.
This implies **role-based views** (driver vs admin) and account/profile management.
- `frontend/js/main.js`
Likely:
- Requests live metrics / video stream
- Updates DOM stats
- Triggers audio (`assets/alert-sound.wav`) + red flash
- `frontend/js/chart-config.js`
Chart.js timeline configuration, rolling window plotting.
- `frontend/css/style.css`
Presentation only, but still include as “Static assets”.

##### Browser (Driver Dashboard / Admin UI)
- HTML pages + JS + Chart.js
- Plays audio, shows alerts, renders chart
##### Flask Backend (app.py)
- Serves static frontend + routes
- API endpoints for metrics/auth
- Possibly an MJPEG/streaming endpoint for live video
##### Drowsiness Detection Module (drowsiness_detector.py + utils)
- Face landmark detection (MediaPipe)
- EAR/MAR computations (SciPy/NumPy)
- State + score + alert level
##### Local Camera Device (Webcam)
- Video frames to backend (likely via OpenCV VideoCapture)
##### SQLite Databases
- `users.db` (auth/account data)
- `driver_data.db` (events, timeline, alerts, sessions)

- Browser ⇄ Flask: HTTP for pages + JSON APIs (metrics, login, register, admin actions)
- Flask → Webcam: frame capture
- Webcam frames → Detector: per-frame processing
- Detector → Flask: metrics (EAR/MAR, blink/yawn counts, score, status)
- Flask → Browser: stream + metrics (polling/WebSocket/Server-Sent Events—label based on what `app.py` does)
- Flask/Auth ↔ `users.db`: credential verification, user CRUD
- Flask/Detector ↔ `driver_data.db`: event logging / history / timeline retrieval

Inside “Backend” show modules and dependencies:
- `app.py` depends on:
- `auth.py` (login/register/session)
- `database.py` (DB connections/queries)
- `drowsiness_detector.py` (start/stop detection, get metrics)
- `drowsiness_detector.py` depends on:
- `utils/eye_tracker.py`
- `utils/yawn_detector.py`
- `utils/alert_manager.py`
- MediaPipe + OpenCV + NumPy/SciPy
- `database.py` manages:
- `users.db`
- `driver_data.db`

##### For each frame
- MediaPipe Face Mesh → 468 landmarks
- `eye_tracker` computes EAR + closure duration/blink rate
- `yawn_detector` computes MAR + yawn events
- `drowsiness_detector` computes score (0–100) + level (Normal/Warning/Alert)
- `alert_manager` applies cooldown/escalation rules
##### Backend pushes to frontend
- Live feed (overlay landmarks) and/or processed frame
- JSON metrics for UI + Chart.js timeline
##### Frontend triggers
- Visual alert (flash/status badge)
- Audio alert (wav)
##### Backend optionally persists
- Alert events, timestamps, session summaries → `driver_data.db`

- A “loop” annotation on the detector pipeline (“per frame @ ~15 FPS”).

##### Architectural patterns/principles to highlight (specific to this project)
- **Modular CV pipeline**: eye tracking, yawn detection, alert policy separated under `backend/utils/`
- **Local-first / offline**: no cloud services; dependencies are on-device libraries + local SQLite
- **State machine / threshold-based scoring**: Normal/Warning/Alert levels + cooldown (alert_manager)

##### Device layer: Webcam

Examples:
- “HTTP GET /login.html”
- “HTTP POST /api/login (username/password)”
- “MJPEG stream /video_feed” or “/api/metrics (JSON: ear, mar, score, status)”
- “SQL: insert alert event”

##### “Don’t overthink it” but be very detailed
Concretely, for this repo, “separating into as many components as possible” means:
- Split backend into `app.py`, `auth.py`, `database.py`, `drowsiness_detector.py`, and each `utils/*` module
- Split frontend into Pages, JS runtime (main.js), Chart config, and Assets
- Split data into the two DB files (not a single generic “DB”)

- Whether metrics are delivered via **polling**, **SSE**, **WebSockets**, or **frame-embedded metadata**

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% =========================
  %% Container / Architecture View (Vertical)
  %% =========================
  subgraph ContainerView["Architecture (Local Offline Full-Stack Monolith)"]
    direction TB

    subgraph ClientLayer["Client Layer (Browser)"]
      direction TB

      Browser["Browser (Driver/Admin)"]:::client

      subgraph Pages["Static Pages (HTML)"]
        direction TB
        DriverUI["Driver Dashboard (driver.html)"]:::frontend
        TimelineUI["Timeline/History (timeline.html)"]:::frontend
        ProfileUI["User Profile (profile.html)"]:::frontend
        AdminUI["Admin Dashboard (admin.html)"]:::frontend
        AdminProfileUI["Admin Profile (admin-profile.html)"]:::frontend
        UserMgmtUI["User Management (user-management.html)"]:::frontend
        LoginUI["Login (login.html)"]:::frontend
        RegisterUI["Register (register.html)"]:::frontend
      end

      subgraph FrontendRuntime["Frontend Runtime (JS/CSS/Assets)"]
        direction TB
        MainJS["main.js (UI updates, fetch metrics/stream, trigger alerts)"]:::frontend
        ChartCfg["chart-config.js (Chart.js timeline config)"]:::frontend
        StyleCSS["style.css"]:::frontend
        AlertWav["alert-sound.wav"]:::asset
        ChartJS["Chart.js (library)"]:::thirdparty
      end
    end

    subgraph ServerLayer["Server Layer (Backend)"]
      direction TB
      FlaskApp["Flask App (Routes, Static Serving, APIs, Streaming)"]:::backend
      AuthSvc["Auth (login/register/admin/session)"]:::backend
      DBLayer["DB Access Layer (SQLite queries/connections)"]:::backend
    end

    subgraph ComputeLayer["Compute Layer (Real-time CV Pipeline)"]
      direction TB
      Detector["Drowsiness Detector (scoring, state machine)"]:::compute
      EyeTracker["Eye Tracker (EAR, blinks/closure)"]:::compute
      YawnDetector["Yawn Detector (MAR, yawns)"]:::compute
      AlertMgr["Alert Manager (cooldown/escalation, when to alert)"]:::compute

      subgraph CVDeps["CV/Math Dependencies (on-device)"]
        direction TB
        OpenCV["OpenCV"]:::thirdparty
        MediaPipe["MediaPipe Face Mesh (468 landmarks)"]:::thirdparty
        NumPySciPy["NumPy/SciPy"]:::thirdparty
      end
    end

    subgraph DataLayer["Data Layer (Local Persistence)"]
      direction TB
      UsersDB[("users.db (accounts/credentials)")]:::db
      DriverDB[("driver_data.db (sessions/events/timeline)")]:::db
    end

    subgraph DeviceLayer["Device Layer"]
      direction TB
      Webcam["Webcam (Local Camera Device)"]:::device
    end
  end

  %% =========================
  %% Main Flows (Runtime Story)
  %% =========================
  Browser -->|"HTTP GET (/driver.html /admin.html /login.html etc)"| FlaskApp
  FlaskApp -->|"Serves static HTML/CSS/JS/assets"| Browser

  Browser -->|"HTTP POST /api/login (username/password)"| AuthSvc
  AuthSvc -->|"SQL select/verify user"| UsersDB
  AuthSvc -->|"HTTP 200/401 (session/cookie)"| Browser

  Browser -->|"Start monitoring (e.g. HTTP POST /start)"| FlaskApp
  FlaskApp -->|"OpenCV VideoCapture() frames"| Webcam

  Webcam -->|"Per-frame capture (~15 FPS)"| Detector
  Detector -->|"Uses landmarks"| MediaPipe
  Detector -->|"Uses frame ops"| OpenCV
  Detector -->|"Uses numeric ops"| NumPySciPy

  Detector -->|"EAR features"| EyeTracker
  Detector -->|"MAR features"| YawnDetector
  EyeTracker -->|"EAR/blink/closure metrics"| Detector
  YawnDetector -->|"MAR/yawn events"| Detector

  Detector -->|"Score+Level (Normal/Warning/Alert)"| AlertMgr
  AlertMgr -->|"Alert decision (cooldown/escalation)"| Detector

  Detector -->|"Metrics (JSON: ear, mar, score, status, counts)"| FlaskApp
  FlaskApp -->|"Metrics delivery (poll/SSE/WS) JSON"| Browser
  FlaskApp -->|"Video stream (MJPEG /video_feed or similar)"| Browser

  Browser -->|"UI alerts (visual badge/flash)"| Browser
  Browser -->|"Play audio alert"| AlertWav

  FlaskApp -->|"SQL insert alert event/session stats"| DriverDB
  FlaskApp -->|"SQL read timeline/history"| DriverDB
  Browser -->|"HTTP GET /timeline (history)"| FlaskApp

  MainJS -->|"Renders timeline/stats"| ChartJS
  ChartCfg -->|"Configures datasets/axes/rolling window"| ChartJS
  StyleCSS -->|"Styles pages"| Pages

  %% =========================
  %% Backend Module / Code-Structure View (Dependencies)
  %% =========================
  subgraph BackendModuleView["Backend Component View (Code Structure)"]
    direction TB

    ReqTxt["Dependencies Spec (requirements.txt)"]:::meta

    AppPy["backend/app.py"]:::code
    AuthPy["backend/auth.py"]:::code
    DatabasePy["backend/database.py"]:::code
    DetectorPy["backend/drowsiness_detector.py"]:::code

    subgraph UtilsPkg["backend/utils (helpers)"]
      direction TB
      UtilsInit["backend/utils/__init__.py"]:::code
      EyePy["backend/utils/eye_tracker.py"]:::code
      YawnPy["backend/utils/yawn_detector.py"]:::code
      AlertPy["backend/utils/alert_manager.py"]:::code
    end

    AppPy -->|"imports/calls"| AuthPy
    AppPy -->|"imports/calls"| DatabasePy
    AppPy -->|"imports/calls"| DetectorPy

    DetectorPy -->|"imports/calls"| EyePy
    DetectorPy -->|"imports/calls"| YawnPy
    DetectorPy -->|"imports/calls"| AlertPy
    DetectorPy -->|"module boundary"| UtilsInit

    DatabasePy -->|"opens/queries"| UsersDB
    DatabasePy -->|"opens/queries"| DriverDB

    ReqTxt -->|"pins"| AppPy
    ReqTxt -->|"pins"| DetectorPy
    ReqTxt -->|"pins"| DatabasePy
  end

  %% =========================
  %% Cross-links (Container nodes to code nodes)
  %% =========================
  FlaskApp -->|"implemented by"| AppPy
  AuthSvc -->|"implemented by"| AuthPy
  DBLayer -->|"implemented by"| DatabasePy
  Detector -->|"implemented by"| DetectorPy
  EyeTracker -->|"implemented by"| EyePy
  YawnDetector -->|"implemented by"| YawnPy
  AlertMgr -->|"implemented by"| AlertPy

  DriverUI -->|"runs in"| Browser
  AdminUI -->|"runs in"| Browser
  LoginUI -->|"runs in"| Browser
  RegisterUI -->|"runs in"| Browser
  TimelineUI -->|"runs in"| Browser
  ProfileUI -->|"runs in"| Browser
  AdminProfileUI -->|"runs in"| Browser
  UserMgmtUI -->|"runs in"| Browser

  MainJS -->|"used by pages"| DriverUI
  MainJS -->|"used by pages"| AdminUI
  MainJS -->|"used by pages"| TimelineUI
  ChartCfg -->|"used by"| TimelineUI

  %% =========================
  %% Click Events (from component mapping)
  %% =========================
  click AppPy "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/app.py"
  click AuthPy "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/auth.py"
  click DatabasePy "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/database.py"
  click DetectorPy "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/drowsiness_detector.py"
  click EyePy "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/utils/eye_tracker.py"
  click YawnPy "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/utils/yawn_detector.py"
  click AlertPy "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/utils/alert_manager.py"
  click UtilsInit "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/utils/__init__.py"
  click UsersDB "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/users.db"
  click DriverDB "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/backend/driver_data.db"

  click DriverUI "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/driver.html"
  click AdminUI "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/admin.html"
  click AdminProfileUI "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/admin-profile.html"
  click LoginUI "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/login.html"
  click RegisterUI "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/register.html"
  click ProfileUI "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/profile.html"
  click TimelineUI "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/timeline.html"
  click UserMgmtUI "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/user-management.html"

  click MainJS "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/js/main.js"
  click ChartCfg "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/js/chart-config.js"
  click StyleCSS "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/css/style.css"
  click AlertWav "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/frontend/assets/alert-sound.wav"
  click ReqTxt "https://github.com/joysjohney/driver-drowsiness-detection/blob/main/requirements.txt"

  %% =========================
  %% Styles (Color is critical)
  %% =========================
  classDef client fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
  classDef frontend fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20
  classDef backend fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
  classDef compute fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C
  classDef db fill:#FFFDE7,stroke:#F9A825,stroke-width:1.5px,color:#7A5D00
  classDef device fill:#FFEBEE,stroke:#C62828,stroke-width:1.5px,color:#B71C1C
  classDef thirdparty fill:#ECEFF1,stroke:#546E7A,stroke-width:1.5px,color:#263238,stroke-dasharray:4 3
  classDef asset fill:#E0F7FA,stroke:#00838F,stroke-width:1.5px,color:#006064
  classDef code fill:#F5F5F5,stroke:#424242,stroke-width:1.5px,color:#212121
  classDef meta fill:#EDE7F6,stroke:#4527A0,stroke-width:1.5px,color:#311B92,stroke-dasharray:4 3
```
