# ayus0-01/alert-drive architecture

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

- Interactive diagram: https://gitdiagram.com/ayus0-01/alert-drive
- Repository: https://github.com/ayus0-01/alert-drive

## Overview

This is a webcam-based driver drowsiness monitor. Its demonstrated runtime captures frames, detects face landmarks, computes eye aspect ratios (EAR), and displays the measurements; the tree also contains a detector, calibration/threshold utilities, and alert outputs. The sampled main loop does not invoke those additional subsystems, so their connections are omitted rather than inferred. Calibration and alert behavior are supported by their own source excerpts.

Main entry points: [`utils/ear.py`](https://github.com/ayus0-01/alert-drive/blob/main/utils/ear.py) (EAR calculation), [`main.py`](https://github.com/ayus0-01/alert-drive/blob/main/main.py) (Webcam capture), [`drowsiness/detector.py`](https://github.com/ayus0-01/alert-drive/blob/main/drowsiness/detector.py) (Closure state detector), [`utils/controlled_calibration.py`](https://github.com/ayus0-01/alert-drive/blob/main/utils/controlled_calibration.py) (Controlled calibration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monitor["Live monitoring"]
  node_camera["Webcam capture<br/>[main.py]"]
  node_landmarks["Face landmarks<br/>[main.py]"]
  node_ear["EAR calculation<br/>[ear.py]"]
  node_display["Video display<br/>[main.py]"]
end

subgraph group_calibration["Calibration"]
  node_controlled_calibration["Controlled calibration"]
  node_ear_calibration["Open-eye calibration<br/>[ear_calibration.py]"]
  node_calibration_data["Calibration data<br/>[calibration.json]"]
end

subgraph group_detection["Drowsiness detection"]
  node_thresholds["Threshold calculation<br/>[thresholds.py]"]
  node_detector["Closure state detector<br/>[detector.py]"]
end

subgraph group_alerts["Alert outputs"]
  node_alert_controller["State alert controller<br/>[controller.py]"]
  node_demo_alert["Beep demo alert<br/>[demo_alert.py]"]
end

node_driver(("Driver"))
node_mediapipe["MediaPipe"]
node_opencv["OpenCV"]

node_driver -->|"provides video"| node_camera
node_camera -->|"passes frames"| node_landmarks
node_mediapipe -->|"detects landmarks"| node_landmarks
node_landmarks -->|"supplies eye points"| node_ear
node_ear -->|"returns EAR"| node_display
node_camera -->|"supplies frames"| node_display
node_opencv -->|"captures frames"| node_camera
node_opencv -->|"renders video"| node_display
node_driver -->|"performs calibration"| node_controlled_calibration
node_controlled_calibration -->|"calculates EAR"| node_ear
node_controlled_calibration -->|"writes statistics"| node_calibration_data
node_driver -->|"performs calibration"| node_ear_calibration
node_ear_calibration -->|"calculates EAR"| node_ear
node_calibration_data -->|"provides calibration"| node_thresholds
node_thresholds -.->|"supplies threshold"| node_detector
node_ear -.->|"supplies eye ratios"| node_detector
node_detector -.->|"produces state"| node_alert_controller
node_detector -.->|"produces state"| node_demo_alert

click node_camera "https://github.com/ayus0-01/alert-drive/blob/main/main.py"
click node_landmarks "https://github.com/ayus0-01/alert-drive/blob/main/main.py"
click node_ear "https://github.com/ayus0-01/alert-drive/blob/main/utils/ear.py"
click node_display "https://github.com/ayus0-01/alert-drive/blob/main/main.py"
click node_controlled_calibration "https://github.com/ayus0-01/alert-drive/blob/main/utils/controlled_calibration.py"
click node_ear_calibration "https://github.com/ayus0-01/alert-drive/blob/main/utils/ear_calibration.py"
click node_calibration_data "https://github.com/ayus0-01/alert-drive/blob/main/config/calibration.json"
click node_thresholds "https://github.com/ayus0-01/alert-drive/blob/main/drowsiness/thresholds.py"
click node_detector "https://github.com/ayus0-01/alert-drive/blob/main/drowsiness/detector.py"
click node_alert_controller "https://github.com/ayus0-01/alert-drive/blob/main/hardware/controller.py"
click node_demo_alert "https://github.com/ayus0-01/alert-drive/blob/main/hardware/demo_alert.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_camera,node_landmarks,node_ear,node_display toneBlue
class node_controlled_calibration,node_ear_calibration,node_calibration_data toneAmber
class node_thresholds,node_detector,node_mediapipe toneMint
class node_alert_controller,node_demo_alert toneRose
class node_driver,node_opencv toneIndigo
```

## Components

### Live monitoring

- [Webcam capture](https://github.com/ayus0-01/alert-drive/blob/main/main.py): `main.py`
- [Face landmarks](https://github.com/ayus0-01/alert-drive/blob/main/main.py): `main.py`
- [EAR calculation](https://github.com/ayus0-01/alert-drive/blob/main/utils/ear.py): `utils/ear.py`
- [Video display](https://github.com/ayus0-01/alert-drive/blob/main/main.py): `main.py`

### Calibration

- [Controlled calibration](https://github.com/ayus0-01/alert-drive/blob/main/utils/controlled_calibration.py): `utils/controlled_calibration.py`
- [Open-eye calibration](https://github.com/ayus0-01/alert-drive/blob/main/utils/ear_calibration.py): `utils/ear_calibration.py`
- [Calibration data](https://github.com/ayus0-01/alert-drive/blob/main/config/calibration.json): `config/calibration.json`

### Drowsiness detection

- [Threshold calculation](https://github.com/ayus0-01/alert-drive/blob/main/drowsiness/thresholds.py): `drowsiness/thresholds.py`
- [Closure state detector](https://github.com/ayus0-01/alert-drive/blob/main/drowsiness/detector.py): `drowsiness/detector.py`

### Alert outputs

- [State alert controller](https://github.com/ayus0-01/alert-drive/blob/main/hardware/controller.py): `hardware/controller.py`
- [Beep demo alert](https://github.com/ayus0-01/alert-drive/blob/main/hardware/demo_alert.py): `hardware/demo_alert.py`

### Other components

- **Driver**
- **MediaPipe**
- **OpenCV**

## Connections

- Driver → Webcam capture: provides video (evidence: `main.py`)
- Webcam capture → Face landmarks: passes frames (evidence: `main.py`)
- MediaPipe → Face landmarks: detects landmarks (evidence: `main.py`)
- Face landmarks → EAR calculation: supplies eye points (evidence: `main.py`)
- EAR calculation → Video display: returns EAR (evidence: `main.py`)
- Webcam capture → Video display: supplies frames (evidence: `main.py`)
- OpenCV → Webcam capture: captures frames (evidence: `main.py`)
- OpenCV → Video display: renders video (evidence: `main.py`)
- Driver → Controlled calibration: performs calibration (evidence: `utils/controlled_calibration.py`)
- Controlled calibration → EAR calculation: calculates EAR (evidence: `utils/controlled_calibration.py`)
- Controlled calibration → Calibration data: writes statistics (evidence: `utils/controlled_calibration.py`)
- Driver → Open-eye calibration: performs calibration (evidence: `utils/ear_calibration.py`)
- Open-eye calibration → EAR calculation: calculates EAR (evidence: `utils/ear_calibration.py`)
- Calibration data → Threshold calculation: provides calibration (evidence: `drowsiness/thresholds.py`)
- Threshold calculation → Closure state detector: supplies threshold
- EAR calculation → Closure state detector: supplies eye ratios
- Closure state detector → State alert controller: produces state
- Closure state detector → Beep demo alert: produces state
