# ahmedsheikh27/sleep_detector architecture

> Architecture diagram of the GitHub repository ahmedsheikh27/sleep_detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmedsheikh27/sleep_detector
- Repository: https://github.com/ahmedsheikh27/sleep_detector

## Overview

Sleep Alarm is a single-camera drowsiness monitor. The main workflow captures and displays webcam frames, detects facial landmarks, computes an average eye-aspect ratio, tracks sustained closure, and plays or stops an alarm; pressing q exits. The repository also contains a separate live face-mesh viewer. The main workflow is visible in app/main.py, while the README documents its threshold behavior and capabilities. The graph keeps the main loop’s responsibilities distinct; several nodes share its source file because they are implemented there.

Main entry points: [`app/main.py`](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py) (Alarm loop), [`app/detectors/fmesh.py`](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/detectors/fmesh.py) (Mesh viewer), [`app/detectors/face_mesh.py`](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/detectors/face_mesh.py) (Face mesh detector), [`app/utils/ears.py`](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/utils/ears.py) (Eye aspect ratio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Alarm runtime"]
  node_main["Alarm loop<br/>[main.py]"]
  node_capture["Frame capture<br/>[main.py]"]
  node_preprocess["Frame preparation<br/>[main.py]"]
  node_closure["Closure tracking<br/>[main.py]"]
end

subgraph group_detection["Face detection"]
  node_face_mesh["Face mesh detector<br/>[face_mesh.py]"]
  node_landmarks["Eye landmarks<br/>[main.py]"]
  node_ear["Eye aspect ratio<br/>[ears.py]"]
  node_viewer["Mesh viewer<br/>[fmesh.py]"]
end

subgraph group_output["Display and audio"]
  node_alarm["Alarm control<br/>[main.py]"]
  node_audio["Alarm audio<br/>[alarm.mp3]"]
  node_display["Camera display<br/>[main.py]"]
end

node_user(("User"))
node_webcam["Webcam"]
node_mediapipe["MediaPipe"]

node_user -->|"starts and quits"| node_main
node_main -->|"opens camera"| node_capture
node_capture -->|"reads frames"| node_webcam
node_main -->|"flips and converts"| node_preprocess
node_preprocess -->|"processes frame"| node_face_mesh
node_face_mesh -->|"uses"| node_mediapipe
node_main -->|"reads results"| node_landmarks
node_main -->|"computes eye ratios"| node_ear
node_main -->|"tracks closed frames"| node_closure
node_main -->|"starts or stops"| node_alarm
node_main -->|"loads"| node_audio
node_main -->|"shows frame"| node_display
node_viewer -->|"uses"| node_mediapipe
node_viewer -->|"reads frames"| node_webcam

click node_main "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py"
click node_capture "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py"
click node_preprocess "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py"
click node_face_mesh "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/detectors/face_mesh.py"
click node_landmarks "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py"
click node_ear "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/utils/ears.py"
click node_closure "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py"
click node_alarm "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py"
click node_audio "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/alarm.mp3"
click node_display "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py"
click node_viewer "https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/detectors/fmesh.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_main,node_capture,node_preprocess,node_closure,node_user toneBlue
class node_face_mesh,node_landmarks,node_ear,node_viewer toneAmber
class node_alarm,node_audio,node_display,node_mediapipe toneMint
class node_webcam toneIndigo
```

## Components

### Alarm runtime

- [Alarm loop](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py): `app/main.py`
- [Frame capture](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py): `app/main.py`
- [Frame preparation](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py): `app/main.py`
- [Closure tracking](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py): `app/main.py`

### Face detection

- [Face mesh detector](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/detectors/face_mesh.py): `app/detectors/face_mesh.py`
- [Eye landmarks](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py): `app/main.py`
- [Eye aspect ratio](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/utils/ears.py): `app/utils/ears.py`
- [Mesh viewer](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/detectors/fmesh.py): `app/detectors/fmesh.py`

### Display and audio

- [Alarm control](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py): `app/main.py`
- [Alarm audio](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/alarm.mp3): `app/alarm.mp3`
- [Camera display](https://github.com/ahmedsheikh27/sleep_detector/blob/main/app/main.py): `app/main.py`

### Other components

- **User**
- **Webcam**
- **MediaPipe**

## Connections

- User → Alarm loop: starts and quits (evidence: `README.md`)
- Alarm loop → Frame capture: opens camera (evidence: `app/main.py`)
- Frame capture → Webcam: reads frames (evidence: `app/main.py`)
- Alarm loop → Frame preparation: flips and converts (evidence: `app/main.py`)
- Frame preparation → Face mesh detector: processes frame (evidence: `app/main.py`)
- Face mesh detector → MediaPipe: uses (evidence: `app/detectors/face_mesh.py`)
- Alarm loop → Eye landmarks: reads results (evidence: `app/main.py`)
- Alarm loop → Eye aspect ratio: computes eye ratios (evidence: `app/main.py`)
- Alarm loop → Closure tracking: tracks closed frames (evidence: `app/main.py`)
- Alarm loop → Alarm control: starts or stops (evidence: `app/main.py`)
- Alarm loop → Alarm audio: loads (evidence: `app/main.py`)
- Alarm loop → Camera display: shows frame (evidence: `app/main.py`)
- Mesh viewer → MediaPipe: uses (evidence: `app/detectors/fmesh.py`)
- Mesh viewer → Webcam: reads frames (evidence: `app/detectors/fmesh.py`)
