# dharanishvijayakumar7-lgtm/ai_driving_assistant architecture

> Architecture diagram of the GitHub repository dharanishvijayakumar7-lgtm/ai_driving_assistant, 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/dharanishvijayakumar7-lgtm/ai_driving_assistant
- Repository: https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant

## Overview

AI Driving Assistant processes webcam or video frames into tracked objects, lane geometry, estimated distances, collision risk, and debounced alerts. Its main result path runs through the staged vision pipeline; users can view annotated output locally or receive frames and metadata in a React dashboard over WebSocket. The README documents the stage sequence and dashboard flow; source excerpts and the SOURCE INDEX support component ownership, but not every internal call is shown.

Main entry points: [`src/pipeline/frame_processor.py`](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/pipeline/frame_processor.py) (Frame Processor), [`src/api/websocket_handler.py`](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/api/websocket_handler.py) (WebSocket Stream), [`frontend/src/App.jsx`](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/App.jsx) (Dashboard App), [`src/pipeline/video_source.py`](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/pipeline/video_source.py) (Video Source)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and API"]
  node_main["Local Runner<br/>[main.py]"]
  node_api["FastAPI App<br/>[app.py]"]
  node_ws["WebSocket Stream"]
  node_schemas["Frame Payload<br/>[schemas.py]"]
end

subgraph group_pipeline["Frame Pipeline"]
  node_video["Video Source<br/>[video_source.py]"]
  node_processor["Frame Processor<br/>[frame_processor.py]"]
  node_resize["Frame Resize<br/>[resize_stage.py]"]
end

subgraph group_perception["Road Perception"]
  node_detection["Object Detection<br/>[stage.py]"]
  node_detector["YOLO Detector<br/>[detector.py]"]
  node_tracker["Object Tracker<br/>[tracker.py]"]
  node_lanes["Lane Detection<br/>[stage.py]"]
  node_lane_detector["Lane Detector<br/>[lane_detector.py]"]
  node_depth["Depth Estimation<br/>[stage.py]"]
  node_depth_model["MiDaS Estimator<br/>[depth_estimator.py]"]
  node_depth_utils["Depth Utilities<br/>[depth_utils.py]"]
end

subgraph group_risk["Risk and Alerts"]
  node_fusion["Collision Fusion<br/>[stage.py]"]
  node_collision["TTC Estimator"]
  node_history["Distance History<br/>[object_history.py]"]
  node_alerts["Alert Stage<br/>[stage.py]"]
  node_manager["Alert Manager<br/>[alert_manager.py]"]
  node_sound["Sound Alert<br/>[sound_alert.py]"]
end

subgraph group_clients["Display Clients"]
  node_display["Frame Renderer<br/>[display.py]"]
  node_hook["WebSocket Hook"]
  node_app["Dashboard App<br/>[App.jsx]"]
  node_feed["Video Feed<br/>[VideoFeed.jsx]"]
  node_banner["Alert Banner<br/>[AlertBanner.jsx]"]
  node_objects["Object Panel<br/>[ObjectPanel.jsx]"]
  node_stats["Stats Bar<br/>[StatsBar.jsx]"]
end

node_driver(("Driver"))
node_browser(("Dashboard User"))

node_driver -->|"provides video"| node_video
node_video -->|"supplies frames"| node_processor
node_processor -->|"runs stages"| node_resize
node_processor -->|"runs stages"| node_detection
node_processor -->|"runs stages"| node_lanes
node_processor -->|"runs stages"| node_depth
node_processor -->|"runs stages"| node_fusion
node_processor -->|"runs stages"| node_alerts
node_detection -->|"uses"| node_detector
node_detection -->|"uses"| node_tracker
node_lanes -->|"uses"| node_lane_detector
node_depth -->|"estimates depth"| node_depth_model
node_depth -->|"extracts distances"| node_depth_utils
node_fusion -->|"computes TTC"| node_collision
node_collision -->|"uses history"| node_history
node_alerts -->|"manages alerts"| node_manager
node_manager -.->|"plays optional beep"| node_sound
node_main -->|"opens source"| node_video
node_main -->|"builds pipeline"| node_processor
node_main -->|"shows frames"| node_display
node_driver -->|"opens dashboard stream"| node_api
node_api -->|"routes stream"| node_ws
node_ws -->|"opens source"| node_video
node_ws -->|"builds pipeline"| node_processor
node_ws -->|"packs metadata"| node_schemas
node_ws -->|"streams frames and JSON"| node_browser
node_browser -->|"connects stream"| node_hook
node_hook -->|"provides stream state"| node_app
node_app -->|"renders frames"| node_feed
node_app -->|"renders alerts"| node_banner
node_app -->|"renders objects"| node_objects
node_app -->|"renders stats"| node_stats
node_alerts -->|"annotates frames"| node_display
node_display -->|"provides annotated frames"| node_ws

click node_video "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/pipeline/video_source.py"
click node_processor "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/pipeline/frame_processor.py"
click node_resize "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/pipeline/resize_stage.py"
click node_detection "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/detection/stage.py"
click node_detector "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/detection/detector.py"
click node_tracker "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/detection/tracker.py"
click node_lanes "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/lanes/stage.py"
click node_lane_detector "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/lanes/lane_detector.py"
click node_depth "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/depth/stage.py"
click node_depth_model "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/depth/depth_estimator.py"
click node_depth_utils "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/depth/depth_utils.py"
click node_fusion "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/fusion/stage.py"
click node_collision "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/fusion/collision_estimator.py"
click node_history "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/fusion/object_history.py"
click node_alerts "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/alerts/stage.py"
click node_manager "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/alerts/alert_manager.py"
click node_sound "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/alerts/sound_alert.py"
click node_main "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/main.py"
click node_api "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/api/app.py"
click node_ws "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/api/websocket_handler.py"
click node_schemas "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/api/schemas.py"
click node_display "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/visualization/display.py"
click node_hook "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/hooks/useWebSocketStream.js"
click node_app "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/App.jsx"
click node_feed "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/components/VideoFeed.jsx"
click node_banner "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/components/AlertBanner.jsx"
click node_objects "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/components/ObjectPanel.jsx"
click node_stats "https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/components/StatsBar.jsx"

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_api,node_ws,node_schemas,node_browser toneBlue
class node_video,node_processor,node_resize toneAmber
class node_detection,node_detector,node_tracker,node_lanes,node_lane_detector,node_depth,node_depth_model,node_depth_utils toneMint
class node_fusion,node_collision,node_history,node_alerts,node_manager,node_sound toneRose
class node_display,node_hook,node_app,node_feed,node_banner,node_objects,node_stats,node_driver toneIndigo
```

## Components

### Entry and API

- [Local Runner](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/main.py): `src/main.py`
- [FastAPI App](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/api/app.py): `src/api/app.py`
- [WebSocket Stream](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/api/websocket_handler.py): `src/api/websocket_handler.py`
- [Frame Payload](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/api/schemas.py): `src/api/schemas.py`

### Frame Pipeline

- [Video Source](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/pipeline/video_source.py): `src/pipeline/video_source.py`
- [Frame Processor](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/pipeline/frame_processor.py): `src/pipeline/frame_processor.py`
- [Frame Resize](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/pipeline/resize_stage.py): `src/pipeline/resize_stage.py`

### Road Perception

- [Object Detection](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/detection/stage.py): `src/detection/stage.py`
- [YOLO Detector](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/detection/detector.py): `src/detection/detector.py`
- [Object Tracker](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/detection/tracker.py): `src/detection/tracker.py`
- [Lane Detection](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/lanes/stage.py): `src/lanes/stage.py`
- [Lane Detector](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/lanes/lane_detector.py): `src/lanes/lane_detector.py`
- [Depth Estimation](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/depth/stage.py): `src/depth/stage.py`
- [MiDaS Estimator](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/depth/depth_estimator.py): `src/depth/depth_estimator.py`
- [Depth Utilities](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/depth/depth_utils.py): `src/depth/depth_utils.py`

### Risk and Alerts

- [Collision Fusion](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/fusion/stage.py): `src/fusion/stage.py`
- [TTC Estimator](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/fusion/collision_estimator.py): `src/fusion/collision_estimator.py`
- [Distance History](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/fusion/object_history.py): `src/fusion/object_history.py`
- [Alert Stage](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/alerts/stage.py): `src/alerts/stage.py`
- [Alert Manager](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/alerts/alert_manager.py): `src/alerts/alert_manager.py`
- [Sound Alert](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/alerts/sound_alert.py): `src/alerts/sound_alert.py`

### Display Clients

- [Frame Renderer](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/src/visualization/display.py): `src/visualization/display.py`
- [WebSocket Hook](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/hooks/useWebSocketStream.js): `frontend/src/hooks/useWebSocketStream.js`
- [Dashboard App](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Video Feed](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/components/VideoFeed.jsx): `frontend/src/components/VideoFeed.jsx`
- [Alert Banner](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/components/AlertBanner.jsx): `frontend/src/components/AlertBanner.jsx`
- [Object Panel](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/components/ObjectPanel.jsx): `frontend/src/components/ObjectPanel.jsx`
- [Stats Bar](https://github.com/dharanishvijayakumar7-lgtm/ai_driving_assistant/blob/main/frontend/src/components/StatsBar.jsx): `frontend/src/components/StatsBar.jsx`

### Other components

- **Driver**
- **Dashboard User**

## Connections

- Driver → Video Source: provides video
- Video Source → Frame Processor: supplies frames
- Frame Processor → Frame Resize: runs stages
- Frame Processor → Object Detection: runs stages
- Frame Processor → Lane Detection: runs stages
- Frame Processor → Depth Estimation: runs stages
- Frame Processor → Collision Fusion: runs stages
- Frame Processor → Alert Stage: runs stages
- Object Detection → YOLO Detector: uses (evidence: `src/detection/stage.py`)
- Object Detection → Object Tracker: uses (evidence: `src/detection/stage.py`)
- Lane Detection → Lane Detector: uses (evidence: `src/lanes/stage.py`)
- Depth Estimation → MiDaS Estimator: estimates depth (evidence: `src/depth/stage.py`)
- Depth Estimation → Depth Utilities: extracts distances (evidence: `src/depth/stage.py`)
- Collision Fusion → TTC Estimator: computes TTC (evidence: `src/fusion/stage.py`)
- TTC Estimator → Distance History: uses history (evidence: `src/fusion/collision_estimator.py`)
- Alert Stage → Alert Manager: manages alerts (evidence: `src/alerts/stage.py`)
- Alert Manager → Sound Alert: plays optional beep (evidence: `src/alerts/alert_manager.py`)
- Local Runner → Video Source: opens source (evidence: `src/main.py`)
- Local Runner → Frame Processor: builds pipeline (evidence: `src/main.py`)
- Local Runner → Frame Renderer: shows frames (evidence: `src/main.py`)
- Driver → FastAPI App: opens dashboard stream
- FastAPI App → WebSocket Stream: routes stream (evidence: `src/api/app.py`)
- WebSocket Stream → Video Source: opens source (evidence: `src/api/websocket_handler.py`)
- WebSocket Stream → Frame Processor: builds pipeline (evidence: `src/api/websocket_handler.py`)
- WebSocket Stream → Frame Payload: packs metadata (evidence: `src/api/websocket_handler.py`)
- WebSocket Stream → Dashboard User: streams frames and JSON
- Dashboard User → WebSocket Hook: connects stream
- WebSocket Hook → Dashboard App: provides stream state (evidence: `frontend/src/App.jsx`)
- Dashboard App → Video Feed: renders frames (evidence: `frontend/src/App.jsx`)
- Dashboard App → Alert Banner: renders alerts (evidence: `frontend/src/App.jsx`)
- Dashboard App → Object Panel: renders objects (evidence: `frontend/src/App.jsx`)
- Dashboard App → Stats Bar: renders stats (evidence: `frontend/src/App.jsx`)
- Alert Stage → Frame Renderer: annotates frames
- Frame Renderer → WebSocket Stream: provides annotated frames (evidence: `src/api/websocket_handler.py`)
