# nan2006-ditha/driver-drowsiness-detection architecture

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

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

## Overview

This is a real-time driver-drowsiness monitoring application: a driver’s camera frames are processed for facial cues, combined into a drowsiness status and metrics, then presented through a FastAPI dashboard and video stream; prolonged eye closure also triggers an alarm. The graph separates frame capture, perception, scoring/alerting, and dashboard delivery, with a secondary model-training branch. The README documents dashboard controls and metrics; source excerpts confirm the API, processing, and metrics paths, but do not show the frontend controls or the eye-classifier implementation.

Main entry points: [`src/detector.py`](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/detector.py) (Frame Processor), [`api/app.py`](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/api/app.py) (FastAPI Routes), [`src/webcam.py`](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/webcam.py) (Webcam Runtime), [`templates/index.html`](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/templates/index.html) (Dashboard Page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and API"]
  node_api["FastAPI Routes<br/>[app.py]"]
  node_webcam["Webcam Runtime<br/>[webcam.py]"]
  node_metrics["Live Metrics<br/>[webcam.py]"]
end

subgraph group_perception["Face Perception"]
  node_face_mesh["MediaPipe Face Mesh"]
  node_detector["Frame Processor<br/>[detector.py]"]
  node_ear["EAR Calculation<br/>[ear.py]"]
  node_mar["MAR Calculation<br/>[mar.py]"]
  node_eye_classifier["Eye Classification<br/>[eye_detector.py]"]
  node_head_pose["Head Pose<br/>[head_pose.py]"]
end

subgraph group_decision["Scoring and Alerts"]
  node_score["Drowsiness Score"]
  node_alarm["Alarm Control<br/>[alarm.py]"]
end

subgraph group_dashboard["Dashboard Delivery"]
  node_page["Dashboard Page<br/>[index.html]"]
  node_script["Metrics Poller<br/>[script.js]"]
  node_styles["Dashboard Styling<br/>[style.css]"]
end

subgraph group_training["Model Training"]
  node_model["CNN Architecture<br/>[cnn_model.py]"]
  node_trainer["CNN Trainer<br/>[train.py]"]
  node_dataset["Eye Image Dataset<br/>[data_loader.py]"]
end

node_driver(("Driver"))
node_browser(("Dashboard User"))
node_camera(("Webcam"))

node_browser -->|"requests dashboard"| node_api
node_api -->|"renders page"| node_page
node_page -->|"loads script"| node_script
node_page -->|"loads styles"| node_styles
node_script -->|"fetches metrics"| node_api
node_api -->|"starts capture"| node_webcam
node_api -->|"streams frames"| node_webcam
node_camera -->|"supplies frames"| node_webcam
node_webcam -->|"processes frames"| node_detector
node_detector -->|"extracts landmarks"| node_face_mesh
node_detector -->|"calculates EAR"| node_ear
node_detector -->|"calculates MAR"| node_mar
node_detector -->|"classifies eyes"| node_eye_classifier
node_detector -->|"estimates pose"| node_head_pose
node_detector -->|"calculates score"| node_score
node_detector -->|"controls alarm"| node_alarm
node_webcam -->|"updates metrics"| node_metrics
node_api -->|"reads metrics"| node_metrics
node_webcam -->|"streams video"| node_browser
node_driver -->|"provides video"| node_camera
node_dataset -.->|"supplies training data"| node_trainer
node_trainer -->|"builds and trains"| node_model

click node_api "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/api/app.py"
click node_webcam "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/webcam.py"
click node_detector "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/detector.py"
click node_ear "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/ear.py"
click node_mar "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/mar.py"
click node_eye_classifier "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/eye_detector.py"
click node_head_pose "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/head_pose.py"
click node_score "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/drowsiness_score.py"
click node_alarm "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/alarm.py"
click node_metrics "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/webcam.py"
click node_page "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/templates/index.html"
click node_script "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/static/script.js"
click node_styles "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/static/style.css"
click node_model "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/cnn_model.py"
click node_trainer "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/train.py"
click node_dataset "https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/data_loader.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_api,node_webcam,node_metrics,node_browser toneBlue
class node_face_mesh,node_detector,node_ear,node_mar,node_eye_classifier,node_head_pose toneAmber
class node_score,node_alarm toneMint
class node_page,node_script,node_styles toneRose
class node_model,node_trainer,node_dataset,node_driver,node_camera toneIndigo
```

## Components

### Capture and API

- [FastAPI Routes](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/api/app.py): `api/app.py`
- [Webcam Runtime](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/webcam.py): `src/webcam.py`
- [Live Metrics](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/webcam.py): `src/webcam.py`

### Face Perception

- **MediaPipe Face Mesh**
- [Frame Processor](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/detector.py): `src/detector.py`
- [EAR Calculation](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/ear.py): `src/ear.py`
- [MAR Calculation](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/mar.py): `src/mar.py`
- [Eye Classification](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/eye_detector.py): `src/eye_detector.py`
- [Head Pose](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/head_pose.py): `src/head_pose.py`

### Scoring and Alerts

- [Drowsiness Score](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/drowsiness_score.py): `src/drowsiness_score.py`
- [Alarm Control](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/alarm.py): `src/alarm.py`

### Dashboard Delivery

- [Dashboard Page](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/templates/index.html): `templates/index.html`
- [Metrics Poller](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/static/script.js): `static/script.js`
- [Dashboard Styling](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/static/style.css): `static/style.css`

### Model Training

- [CNN Architecture](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/cnn_model.py): `src/cnn_model.py`
- [CNN Trainer](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/train.py): `src/train.py`
- [Eye Image Dataset](https://github.com/nan2006-ditha/driver-drowsiness-detection/blob/main/src/data_loader.py): `src/data_loader.py`

### Other components

- **Driver**
- **Dashboard User**
- **Webcam**

## Connections

- Dashboard User → FastAPI Routes: requests dashboard
- FastAPI Routes → Dashboard Page: renders page
- Dashboard Page → Metrics Poller: loads script
- Dashboard Page → Dashboard Styling: loads styles
- Metrics Poller → FastAPI Routes: fetches metrics
- FastAPI Routes → Webcam Runtime: starts capture
- FastAPI Routes → Webcam Runtime: streams frames
- Webcam → Webcam Runtime: supplies frames
- Webcam Runtime → Frame Processor: processes frames
- Frame Processor → MediaPipe Face Mesh: extracts landmarks
- Frame Processor → EAR Calculation: calculates EAR
- Frame Processor → MAR Calculation: calculates MAR
- Frame Processor → Eye Classification: classifies eyes
- Frame Processor → Head Pose: estimates pose
- Frame Processor → Drowsiness Score: calculates score
- Frame Processor → Alarm Control: controls alarm
- Webcam Runtime → Live Metrics: updates metrics
- FastAPI Routes → Live Metrics: reads metrics
- Webcam Runtime → Dashboard User: streams video
- Driver → Webcam: provides video
- Eye Image Dataset → CNN Trainer: supplies training data
- CNN Trainer → CNN Architecture: builds and trains