# sanjana-ml/driver-safety-system architecture

> Architecture diagram of the GitHub repository sanjana-ml/driver-safety-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanjana-ml/driver-safety-system
- Repository: https://github.com/sanjana-ml/driver-safety-system

## Overview

This is a laptop-webcam driver-drowsiness monitoring system, with a separate model-training and evaluation workflow. In live use, the GUI or console entry point captures frames and passes them to the pipeline, which checks face landmarks and frame quality, calibrates and selects cues, combines CNN predictions with temporal and confidence checks, then reports status and can trigger an audio alert. The README documents reporting and training capabilities not fully sampled; those branches are shown where documented, while implementation details and some internal calls remain unverified.

Main entry points: [`utils/pipeline.py`](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/pipeline.py) (Detection pipeline), [`gui/app.py`](https://github.com/sanjana-ml/driver-safety-system/blob/main/gui/app.py) (Monitoring GUI), [`predict.py`](https://github.com/sanjana-ml/driver-safety-system/blob/main/predict.py) (Console monitor), [`utils/cue_selector.py`](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/cue_selector.py) (Adaptive cue selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_live["Live monitoring"]
  node_gui["Monitoring GUI<br/>[app.py]"]
  node_main["GUI entry point<br/>[main.py]"]
  node_console["Console monitor<br/>[predict.py]"]
  node_camera["Webcam capture<br/>[camera.py]"]
  node_alert["Audio alert<br/>[alert.py]"]
  node_images["Image overlays<br/>[image_utils.py]"]
end

subgraph group_vision["Vision and inference"]
  node_pipeline["Detection pipeline<br/>[pipeline.py]"]
  node_landmarks["Face landmarks<br/>[landmarks.py]"]
  node_quality["Frame quality gate<br/>[quality.py]"]
  node_cues["Adaptive cue selection<br/>[cue_selector.py]"]
  node_calibration["Driver calibration<br/>[calibration.py]"]
  node_pose["Head pose<br/>[head_pose.py]"]
  node_perclos["PERCLOS tracking<br/>[perclos.py]"]
  node_window["Temporal voting<br/>[sliding_window.py]"]
  node_model["CNN classifier<br/>[cnn_cbam.py]"]
  node_cbam["CBAM attention<br/>[cbam.py]"]
end

subgraph group_learning["Training and evaluation"]
  node_dataset["Dataset loading<br/>[data_loader.py]"]
  node_trainer["Model training<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_test_runner["Re-evaluation runner<br/>[run_tests.py]"]
end

subgraph group_support["Shared support"]
  node_logs[("Logs and reports<br/>[logger.py]")]
  node_config["System configuration<br/>[config.py]"]
  node_exceptions["Error handling<br/>[exceptions.py]"]
end

node_driver(("Driver"))

node_driver -->|"starts monitoring"| node_main
node_driver -->|"starts monitoring"| node_console
node_main -->|"launches"| node_gui
node_gui -->|"starts capture"| node_camera
node_console -->|"reads frames"| node_camera
node_gui -->|"processes frames"| node_pipeline
node_console -->|"processes frames"| node_pipeline
node_pipeline -->|"detects face"| node_landmarks
node_pipeline -->|"checks quality"| node_quality
node_pipeline -->|"calibrates cues"| node_calibration
node_pipeline -->|"selects cues"| node_cues
node_pipeline -->|"predicts drowsiness"| node_model
node_pipeline -->|"tracks eye closure"| node_perclos
node_pipeline -->|"smooths predictions"| node_window
node_cues -->|"uses thresholds"| node_calibration
node_cues -->|"reads landmarks"| node_landmarks
node_cues -->|"checks reliability"| node_quality
node_pipeline -->|"estimates pose"| node_pose
node_model -->|"applies attention"| node_cbam
node_gui -->|"controls alarm"| node_alert
node_gui -->|"draws overlays"| node_images
node_trainer -->|"loads samples"| node_dataset
node_trainer -->|"builds classifier"| node_model
node_trainer -->|"evaluates model"| node_evaluation
node_test_runner -->|"loads test data"| node_dataset
node_test_runner -->|"generates reports"| node_evaluation
node_evaluation -->|"writes metrics"| node_logs
node_gui -->|"logs predictions"| node_logs
node_console -->|"logs predictions"| node_logs
node_pipeline -->|"uses thresholds"| node_config
node_camera -->|"raises camera errors"| node_exceptions
node_dataset -->|"raises dataset errors"| node_exceptions

click node_gui "https://github.com/sanjana-ml/driver-safety-system/blob/main/gui/app.py"
click node_main "https://github.com/sanjana-ml/driver-safety-system/blob/main/main.py"
click node_console "https://github.com/sanjana-ml/driver-safety-system/blob/main/predict.py"
click node_camera "https://github.com/sanjana-ml/driver-safety-system/blob/main/camera.py"
click node_pipeline "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/pipeline.py"
click node_landmarks "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/landmarks.py"
click node_quality "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/quality.py"
click node_cues "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/cue_selector.py"
click node_calibration "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/calibration.py"
click node_pose "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/head_pose.py"
click node_perclos "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/perclos.py"
click node_window "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/sliding_window.py"
click node_model "https://github.com/sanjana-ml/driver-safety-system/blob/main/models/cnn_cbam.py"
click node_cbam "https://github.com/sanjana-ml/driver-safety-system/blob/main/cbam/cbam.py"
click node_alert "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/alert.py"
click node_images "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/image_utils.py"
click node_dataset "https://github.com/sanjana-ml/driver-safety-system/blob/main/training/data_loader.py"
click node_trainer "https://github.com/sanjana-ml/driver-safety-system/blob/main/train.py"
click node_evaluation "https://github.com/sanjana-ml/driver-safety-system/blob/main/testing/evaluate.py"
click node_test_runner "https://github.com/sanjana-ml/driver-safety-system/blob/main/testing/run_tests.py"
click node_logs "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/logger.py"
click node_config "https://github.com/sanjana-ml/driver-safety-system/blob/main/config.py"
click node_exceptions "https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/exceptions.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_gui,node_main,node_console,node_camera,node_alert,node_images toneBlue
class node_pipeline,node_landmarks,node_quality,node_cues,node_calibration,node_pose,node_perclos,node_window,node_model,node_cbam toneAmber
class node_dataset,node_trainer,node_evaluation,node_test_runner toneMint
class node_logs,node_config,node_exceptions toneRose
class node_driver toneIndigo
```

## Components

### Live monitoring

- [Monitoring GUI](https://github.com/sanjana-ml/driver-safety-system/blob/main/gui/app.py): `gui/app.py`
- [GUI entry point](https://github.com/sanjana-ml/driver-safety-system/blob/main/main.py): `main.py`
- [Console monitor](https://github.com/sanjana-ml/driver-safety-system/blob/main/predict.py): `predict.py`
- [Webcam capture](https://github.com/sanjana-ml/driver-safety-system/blob/main/camera.py): `camera.py`
- [Audio alert](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/alert.py): `utils/alert.py`
- [Image overlays](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/image_utils.py): `utils/image_utils.py`

### Vision and inference

- [Detection pipeline](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/pipeline.py): `utils/pipeline.py`
- [Face landmarks](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/landmarks.py): `utils/landmarks.py`
- [Frame quality gate](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/quality.py): `utils/quality.py`
- [Adaptive cue selection](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/cue_selector.py): `utils/cue_selector.py`
- [Driver calibration](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/calibration.py): `utils/calibration.py`
- [Head pose](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/head_pose.py): `utils/head_pose.py`
- [PERCLOS tracking](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/perclos.py): `utils/perclos.py`
- [Temporal voting](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/sliding_window.py): `utils/sliding_window.py`
- [CNN classifier](https://github.com/sanjana-ml/driver-safety-system/blob/main/models/cnn_cbam.py): `models/cnn_cbam.py`
- [CBAM attention](https://github.com/sanjana-ml/driver-safety-system/blob/main/cbam/cbam.py): `cbam/cbam.py`

### Training and evaluation

- [Dataset loading](https://github.com/sanjana-ml/driver-safety-system/blob/main/training/data_loader.py): `training/data_loader.py`
- [Model training](https://github.com/sanjana-ml/driver-safety-system/blob/main/train.py): `train.py`
- [Model evaluation](https://github.com/sanjana-ml/driver-safety-system/blob/main/testing/evaluate.py): `testing/evaluate.py`
- [Re-evaluation runner](https://github.com/sanjana-ml/driver-safety-system/blob/main/testing/run_tests.py): `testing/run_tests.py`

### Shared support

- [Logs and reports](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/logger.py): `utils/logger.py`
- [System configuration](https://github.com/sanjana-ml/driver-safety-system/blob/main/config.py): `config.py`
- [Error handling](https://github.com/sanjana-ml/driver-safety-system/blob/main/utils/exceptions.py): `utils/exceptions.py`

### Other components

- **Driver**

## Connections

- Driver → GUI entry point: starts monitoring (evidence: `README.md`)
- Driver → Console monitor: starts monitoring (evidence: `README.md`)
- GUI entry point → Monitoring GUI: launches (evidence: `main.py`)
- Monitoring GUI → Webcam capture: starts capture (evidence: `gui/app.py`)
- Console monitor → Webcam capture: reads frames (evidence: `predict.py`)
- Monitoring GUI → Detection pipeline: processes frames (evidence: `gui/app.py`)
- Console monitor → Detection pipeline: processes frames (evidence: `predict.py`)
- Detection pipeline → Face landmarks: detects face (evidence: `utils/pipeline.py`)
- Detection pipeline → Frame quality gate: checks quality (evidence: `utils/pipeline.py`)
- Detection pipeline → Driver calibration: calibrates cues (evidence: `utils/pipeline.py`)
- Detection pipeline → Adaptive cue selection: selects cues (evidence: `utils/pipeline.py`)
- Detection pipeline → CNN classifier: predicts drowsiness (evidence: `utils/pipeline.py`)
- Detection pipeline → PERCLOS tracking: tracks eye closure (evidence: `utils/pipeline.py`)
- Detection pipeline → Temporal voting: smooths predictions (evidence: `utils/pipeline.py`)
- Adaptive cue selection → Driver calibration: uses thresholds (evidence: `utils/cue_selector.py`)
- Adaptive cue selection → Face landmarks: reads landmarks (evidence: `utils/cue_selector.py`)
- Adaptive cue selection → Frame quality gate: checks reliability (evidence: `utils/cue_selector.py`)
- Detection pipeline → Head pose: estimates pose (evidence: `utils/pipeline.py`)
- CNN classifier → CBAM attention: applies attention (evidence: `models/cnn_cbam.py`)
- Monitoring GUI → Audio alert: controls alarm (evidence: `gui/app.py`)
- Monitoring GUI → Image overlays: draws overlays (evidence: `gui/app.py`)
- Model training → Dataset loading: loads samples (evidence: `train.py`)
- Model training → CNN classifier: builds classifier (evidence: `train.py`)
- Model training → Model evaluation: evaluates model (evidence: `train.py`)
- Re-evaluation runner → Dataset loading: loads test data (evidence: `testing/run_tests.py`)
- Re-evaluation runner → Model evaluation: generates reports (evidence: `testing/run_tests.py`)
- Model evaluation → Logs and reports: writes metrics (evidence: `README.md`)
- Monitoring GUI → Logs and reports: logs predictions (evidence: `gui/app.py`)
- Console monitor → Logs and reports: logs predictions (evidence: `predict.py`)
- Detection pipeline → System configuration: uses thresholds (evidence: `utils/pipeline.py`)
- Webcam capture → Error handling: raises camera errors (evidence: `camera.py`)
- Dataset loading → Error handling: raises dataset errors (evidence: `training/data_loader.py`)
