# bhuvzzs24-spec/safe-drive architecture

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

- Interactive diagram: https://gitdiagram.com/bhuvzzs24-spec/safe-drive
- Repository: https://github.com/bhuvzzs24-spec/safe-drive

## Overview

SAFE-Drive is a research toolkit for calibrated traffic-video safety analysis, with both a command-line runner and a local review dashboard. The main workflow analyzes local video or an RTSP stream, detects and tracks road users, estimates speed when calibration is valid, screens encounters and configurable speed rules, and records events and annotated output for review. The dashboard adds bounded background jobs, saved sessions and reviewer decisions. The graph also preserves the optional helmet-analysis and dataset-validation branch. Some edges rely on README statements or source-index references because the relevant implementation was not excerpted.

Main entry points: [`src/safe_drive/cli.py`](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/cli.py) (Video CLI), [`app.py`](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/app.py) (Review Dashboard), [`src/safe_drive/worker.py`](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/worker.py) (Worker Process), [`src/safe_drive/job_runner.py`](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/job_runner.py) (Job Supervision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["Video CLI<br/>[cli.py]"]
  node_dashboard["Review Dashboard<br/>[app.py]"]
  node_frontend["Dashboard UI<br/>[app.js]"]
end

subgraph group_analysis["Video Analysis"]
  node_camera["Camera Input<br/>[camera_input.py]"]
  node_vision["Detection Models<br/>[vision.py]"]
  node_tracking["Object Tracking<br/>[tracking.py]"]
  node_timestamps["Video Timing<br/>[video_time.py]"]
end

subgraph group_signals["Safety Signals"]
  node_geometry["Road Calibration<br/>[geometry.py]"]
  node_speed["Speed Estimates<br/>[speed.py]"]
  node_encounters["Encounter Screening<br/>[encounters.py]"]
  node_risk["Risk Scoring<br/>[risk.py]"]
  node_rules["Event Rules<br/>[rules.py]"]
  node_legacy["Legacy Risk Engine<br/>[risk_engine.py]"]
end

subgraph group_review["Jobs and Review"]
  node_events["Event Records<br/>[events.py]"]
  node_jobs["Job Supervision<br/>[job_runner.py]"]
  node_worker["Worker Process<br/>[worker.py]"]
  node_storage[("SQLite History<br/>[storage.py]")]
  node_security["Access Controls<br/>[security.py]"]
  node_runtime["Runtime Status<br/>[runtime_status.py]"]
end

subgraph group_helmet["Helmet Research"]
  node_helmet["Helmet Analysis<br/>[helmet.py]"]
  node_helmetdata["Dataset Validation<br/>[helmet_dataset.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs analysis"| node_cli
node_operator -->|"reviews video"| node_dashboard
node_dashboard -->|"serves interface"| node_frontend
node_dashboard -->|"supervises jobs"| node_jobs
node_dashboard -->|"reads and writes"| node_storage
node_dashboard -->|"enforces access"| node_security
node_dashboard -->|"reports status"| node_runtime
node_jobs -.->|"starts worker"| node_worker
node_worker -->|"runs video"| node_cli
node_worker -->|"configures rule"| node_rules
node_worker -->|"saves progress"| node_storage
node_worker -->|"checks weights"| node_vision
node_cli -->|"detects objects"| node_vision
node_cli -->|"tracks objects"| node_tracking
node_cli -->|"uses timestamps"| node_timestamps
node_cli -->|"maps road plane"| node_geometry
node_cli -->|"estimates speed"| node_speed
node_cli -->|"screens encounters"| node_encounters
node_cli -->|"scores risk"| node_risk
node_cli -->|"applies rules"| node_rules
node_cli -->|"records events"| node_events
node_cli -->|"optionally analyzes"| node_helmet
node_helmetdata -->|"uses class schema"| node_helmet
node_operator -.->|"prepares research data"| node_helmetdata
node_legacy -.->|"prototype comparison"| node_operator

click node_cli "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/cli.py"
click node_dashboard "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/app.py"
click node_frontend "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/static/app.js"
click node_camera "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/camera_input.py"
click node_vision "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/vision.py"
click node_tracking "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/tracking.py"
click node_timestamps "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/video_time.py"
click node_geometry "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/geometry.py"
click node_speed "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/speed.py"
click node_encounters "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/encounters.py"
click node_risk "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/risk.py"
click node_rules "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/rules.py"
click node_events "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/events.py"
click node_jobs "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/job_runner.py"
click node_worker "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/worker.py"
click node_storage "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/storage.py"
click node_security "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/security.py"
click node_runtime "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/runtime_status.py"
click node_helmet "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/helmet.py"
click node_helmetdata "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/helmet_dataset.py"
click node_legacy "https://github.com/bhuvzzs24-spec/safe-drive/blob/main/legacy/risk_engine.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_cli,node_dashboard,node_frontend toneBlue
class node_camera,node_vision,node_tracking,node_timestamps toneAmber
class node_geometry,node_speed,node_encounters,node_risk,node_rules,node_legacy toneMint
class node_events,node_jobs,node_worker,node_storage,node_security,node_runtime toneRose
class node_helmet,node_helmetdata,node_operator toneIndigo
```

## Components

### User Interfaces

- [Video CLI](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/cli.py): `src/safe_drive/cli.py`
- [Review Dashboard](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/app.py): `app.py`
- [Dashboard UI](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/static/app.js): `static/app.js`

### Video Analysis

- [Camera Input](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/camera_input.py): `src/safe_drive/camera_input.py`
- [Detection Models](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/vision.py): `src/safe_drive/vision.py`
- [Object Tracking](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/tracking.py): `src/safe_drive/tracking.py`
- [Video Timing](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/video_time.py): `src/safe_drive/video_time.py`

### Safety Signals

- [Road Calibration](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/geometry.py): `src/safe_drive/geometry.py`
- [Speed Estimates](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/speed.py): `src/safe_drive/speed.py`
- [Encounter Screening](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/encounters.py): `src/safe_drive/encounters.py`
- [Risk Scoring](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/risk.py): `src/safe_drive/risk.py`
- [Event Rules](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/rules.py): `src/safe_drive/rules.py`
- [Legacy Risk Engine](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/legacy/risk_engine.py): `legacy/risk_engine.py`

### Jobs and Review

- [Event Records](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/events.py): `src/safe_drive/events.py`
- [Job Supervision](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/job_runner.py): `src/safe_drive/job_runner.py`
- [Worker Process](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/worker.py): `src/safe_drive/worker.py`
- [SQLite History](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/storage.py): `src/safe_drive/storage.py`
- [Access Controls](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/security.py): `src/safe_drive/security.py`
- [Runtime Status](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/runtime_status.py): `src/safe_drive/runtime_status.py`

### Helmet Research

- [Helmet Analysis](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/helmet.py): `src/safe_drive/helmet.py`
- [Dataset Validation](https://github.com/bhuvzzs24-spec/safe-drive/blob/main/src/safe_drive/helmet_dataset.py): `src/safe_drive/helmet_dataset.py`

### Other components

- **Operator**

## Connections

- Operator → Video CLI: runs analysis (evidence: `README.md`)
- Operator → Review Dashboard: reviews video (evidence: `README.md`)
- Review Dashboard → Dashboard UI: serves interface (evidence: `README.md`)
- Review Dashboard → Job Supervision: supervises jobs (evidence: `app.py`)
- Review Dashboard → SQLite History: reads and writes (evidence: `app.py`)
- Review Dashboard → Access Controls: enforces access (evidence: `app.py`)
- Review Dashboard → Runtime Status: reports status (evidence: `app.py`)
- Job Supervision → Worker Process: starts worker
- Worker Process → Video CLI: runs video (evidence: `src/safe_drive/worker.py`)
- Worker Process → Event Rules: configures rule (evidence: `src/safe_drive/worker.py`)
- Worker Process → SQLite History: saves progress (evidence: `src/safe_drive/worker.py`)
- Worker Process → Detection Models: checks weights (evidence: `src/safe_drive/worker.py`)
- Video CLI → Detection Models: detects objects (evidence: `src/safe_drive/cli.py`)
- Video CLI → Object Tracking: tracks objects (evidence: `src/safe_drive/cli.py`)
- Video CLI → Video Timing: uses timestamps (evidence: `src/safe_drive/cli.py`)
- Video CLI → Road Calibration: maps road plane (evidence: `src/safe_drive/cli.py`)
- Video CLI → Speed Estimates: estimates speed (evidence: `src/safe_drive/cli.py`)
- Video CLI → Encounter Screening: screens encounters (evidence: `src/safe_drive/cli.py`)
- Video CLI → Risk Scoring: scores risk (evidence: `src/safe_drive/cli.py`)
- Video CLI → Event Rules: applies rules (evidence: `src/safe_drive/cli.py`)
- Video CLI → Event Records: records events (evidence: `src/safe_drive/cli.py`)
- Video CLI → Helmet Analysis: optionally analyzes (evidence: `src/safe_drive/cli.py`)
- Dataset Validation → Helmet Analysis: uses class schema (evidence: `src/safe_drive/helmet_dataset.py`)
- Operator → Dataset Validation: prepares research data
- Legacy Risk Engine → Operator: prototype comparison