# jam9973/blink-reminder architecture

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

- Interactive diagram: https://gitdiagram.com/jam9973/blink-reminder
- Repository: https://github.com/jam9973/blink-reminder

## Overview

This is a desktop blink-monitoring prototype: it reads webcam frames, derives eye measurements, counts blinks over a rolling 60-second window, and alerts when the count stays below a configurable target. The principal flow is frame capture and EAR measurement, C-based blink and alert decisions, then on-screen feedback and optional measurement logging. Settings cover camera and thresholds; the README also documents landmark display, keyboard/mouse controls, and CSV/JSON records. The source index confirms key Python imports; some UI-to-worker wiring is documented only at product level, so uncertain links are omitted.

Main entry points: [`blink_app.py`](https://github.com/jam9973/blink-reminder/blob/main/blink_app.py) (Desktop App), [`camera_worker.py`](https://github.com/jam9973/blink-reminder/blob/main/camera_worker.py) (Frame Analysis), [`engine.py`](https://github.com/jam9973/blink-reminder/blob/main/engine.py) (Python Bridge), [`app_settings.py`](https://github.com/jam9973/blink-reminder/blob/main/app_settings.py) (App Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and Settings"]
  node_camera_worker["Frame Analysis<br/>[camera_worker.py]"]
  node_settings["App Settings<br/>[app_settings.py]"]
  node_settings_file["Saved Settings<br/>[app_settings.py]"]
end

subgraph group_decision["Blink Decisions"]
  node_engine_bridge["Python Bridge<br/>[engine.py]"]
  node_c_engine["Blink Engine<br/>[blink_engine.c]"]
  node_c_api["C API<br/>[blink_engine.h]"]
end

subgraph group_presentation["App and Records"]
  node_app["Desktop App<br/>[blink_app.py]"]
  node_measurement_log["Measurement Logger<br/>[measurement_log.py]"]
  node_csv_records["CSV Records<br/>[measurement_log.py]"]
  node_alert["On-screen Alert<br/>[blink_app.py]"]
end

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

node_webcam -->|"provides frames"| node_camera_worker
node_camera_worker -->|"detects landmarks"| node_mediapipe
node_camera_worker -->|"imports"| node_settings
node_camera_worker -->|"imports"| node_engine_bridge
node_app -->|"imports"| node_engine_bridge
node_app -->|"imports"| node_measurement_log
node_engine_bridge -->|"calls via ctypes"| node_c_engine
node_c_engine -->|"implements"| node_c_api
node_app -->|"displays"| node_alert
node_app -->|"accepts controls"| node_user
node_measurement_log -->|"writes"| node_csv_records
node_settings -->|"persists"| node_settings_file

click node_camera_worker "https://github.com/jam9973/blink-reminder/blob/main/camera_worker.py"
click node_settings "https://github.com/jam9973/blink-reminder/blob/main/app_settings.py"
click node_app "https://github.com/jam9973/blink-reminder/blob/main/blink_app.py"
click node_engine_bridge "https://github.com/jam9973/blink-reminder/blob/main/engine.py"
click node_c_engine "https://github.com/jam9973/blink-reminder/blob/main/blink_engine.c"
click node_c_api "https://github.com/jam9973/blink-reminder/blob/main/blink_engine.h"
click node_measurement_log "https://github.com/jam9973/blink-reminder/blob/main/measurement_log.py"
click node_csv_records "https://github.com/jam9973/blink-reminder/blob/main/measurement_log.py"
click node_settings_file "https://github.com/jam9973/blink-reminder/blob/main/app_settings.py"
click node_alert "https://github.com/jam9973/blink-reminder/blob/main/blink_app.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_worker,node_settings,node_settings_file,node_user toneBlue
class node_engine_bridge,node_c_engine,node_c_api toneAmber
class node_app,node_measurement_log,node_csv_records,node_alert,node_mediapipe toneMint
class node_webcam toneIndigo
```

## Components

### Capture and Settings

- [Frame Analysis](https://github.com/jam9973/blink-reminder/blob/main/camera_worker.py): `camera_worker.py`
- [App Settings](https://github.com/jam9973/blink-reminder/blob/main/app_settings.py): `app_settings.py`
- [Saved Settings](https://github.com/jam9973/blink-reminder/blob/main/app_settings.py): `app_settings.py`

### Blink Decisions

- [Python Bridge](https://github.com/jam9973/blink-reminder/blob/main/engine.py): `engine.py`
- [Blink Engine](https://github.com/jam9973/blink-reminder/blob/main/blink_engine.c): `blink_engine.c`
- [C API](https://github.com/jam9973/blink-reminder/blob/main/blink_engine.h): `blink_engine.h`

### App and Records

- [Desktop App](https://github.com/jam9973/blink-reminder/blob/main/blink_app.py): `blink_app.py`
- [Measurement Logger](https://github.com/jam9973/blink-reminder/blob/main/measurement_log.py): `measurement_log.py`
- [CSV Records](https://github.com/jam9973/blink-reminder/blob/main/measurement_log.py): `measurement_log.py`
- [On-screen Alert](https://github.com/jam9973/blink-reminder/blob/main/blink_app.py): `blink_app.py`

### Other components

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

## Connections

- Webcam → Frame Analysis: provides frames
- Frame Analysis → MediaPipe: detects landmarks
- Frame Analysis → App Settings: imports (evidence: `camera_worker.py`)
- Frame Analysis → Python Bridge: imports (evidence: `camera_worker.py`)
- Desktop App → Python Bridge: imports (evidence: `blink_app.py`)
- Desktop App → Measurement Logger: imports (evidence: `blink_app.py`)
- Python Bridge → Blink Engine: calls via ctypes
- Blink Engine → C API: implements (evidence: `blink_engine.c`)
- Desktop App → On-screen Alert: displays (evidence: `blink_app.py`)
- Desktop App → User: accepts controls
- Measurement Logger → CSV Records: writes (evidence: `measurement_log.py`)
- App Settings → Saved Settings: persists (evidence: `app_settings.py`)
