# paavansirivardhan123/visiona architecture

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

- Interactive diagram: https://gitdiagram.com/paavansirivardhan123/visiona
- Repository: https://github.com/paavansirivardhan123/visiona

## Overview

Visiona AI is a hands-free assistive navigation application. Camera frames pass through perception and motion analysis; detections are prioritized and converted into spoken guidance and proximity alerts. In parallel, push-to-talk commands reach an LLM tool router for scene-memory, goal-search, and walking-directions tasks. The README documents broader capabilities, including custom object recognition and multi-camera operation. Edges are limited to relationships shown by sampled source, SOURCE INDEX references, or README statements; several documented subsystems have only directory-level paths because their implementation was not sampled.

Main entry points: [`main.py`](https://github.com/paavansirivardhan123/visiona/blob/main/main.py) (Application loop), [`perception/vision.py`](https://github.com/paavansirivardhan123/visiona/blob/main/perception/vision.py) (Detection pipeline), [`agents/tools/vision_tools.py`](https://github.com/paavansirivardhan123/visiona/blob/main/agents/tools/vision_tools.py) (Assistant tools), [`perception/tracker.py`](https://github.com/paavansirivardhan123/visiona/blob/main/perception/tracker.py) (Object tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and orchestration"]
  node_main["Application loop<br/>[main.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_perception["Spatial perception"]
  node_vision["Detection pipeline<br/>[vision.py]"]
  node_depth["Monocular depth<br/>[mono_depth.py]"]
  node_tracker["Object tracking<br/>[tracker.py]"]
  node_kalman["Depth filtering<br/>[kalman.py]"]
  node_egomotion["User motion<br/>[egomotion.py]"]
  node_speed["Object speed<br/>[speed.py]"]
  node_ttc["Collision timing<br/>[ttc.py]"]
  node_detection["Spatial records<br/>[detection.py]"]
end

subgraph group_guidance["Threat and audio guidance"]
  node_priority["Threat priority<br/>[priority_queue.py]"]
  node_heatmap["Message grouping<br/>[heatmap.py]"]
  node_speech["Speech output<br/>[speech.py]"]
  node_alert["Proximity beeps<br/>[alert.py]"]
end

subgraph group_assistant["Voice and reasoning"]
  node_voice["Push-to-talk<br/>[voice_input.py]"]
  node_agent["Reasoning router<br/>[orchestrator.py]"]
  node_tools["Assistant tools<br/>[vision_tools.py]"]
  node_recognition["Custom recognition<br/>[recognition.py]"]
end

subgraph group_services["Memory and navigation"]
  node_memory[("Visual memory and goals<br/>[memory.py]")]
  node_maps["Walking directions<br/>[google_maps.py]"]
  node_vector[("Object signatures<br/>[vector_db.py]")]
end

node_user(("User"))
node_cameras(("Camera feeds"))
node_maps_api["Google Maps API"]

node_user -->|"speaks commands"| node_voice
node_cameras -->|"provide frames"| node_main
node_main -->|"processes frames"| node_vision
node_main -->|"reads settings"| node_config
node_vision -->|"estimates distance"| node_depth
node_vision -->|"tracks detections"| node_tracker
node_tracker -->|"filters depth"| node_kalman
node_vision -->|"estimates user motion"| node_egomotion
node_vision -->|"estimates speed"| node_speed
node_vision -->|"computes collision time"| node_ttc
node_vision -->|"creates records"| node_detection
node_main -->|"prioritizes detections"| node_priority
node_main -->|"builds guidance"| node_heatmap
node_main -->|"queues speech"| node_speech
node_main -->|"triggers alerts"| node_alert
node_user -->|"operates interface"| node_main
node_main -->|"captures speech"| node_voice
node_main -->|"routes commands"| node_agent
node_agent -->|"dispatches tools"| node_tools
node_main -->|"uses recognition"| node_recognition
node_main -->|"updates and checks"| node_memory
node_tools -->|"reads and updates"| node_memory
node_tools -->|"requests route"| node_maps
node_tools -->|"queries signatures"| node_vector
node_maps -->|"fetches directions"| node_maps_api
node_speech -->|"speaks guidance"| node_user

click node_main "https://github.com/paavansirivardhan123/visiona/blob/main/main.py"
click node_config "https://github.com/paavansirivardhan123/visiona/blob/main/core/config.py"
click node_vision "https://github.com/paavansirivardhan123/visiona/blob/main/perception/vision.py"
click node_depth "https://github.com/paavansirivardhan123/visiona/blob/main/perception/mono_depth.py"
click node_tracker "https://github.com/paavansirivardhan123/visiona/blob/main/perception/tracker.py"
click node_kalman "https://github.com/paavansirivardhan123/visiona/blob/main/kinematics/kalman.py"
click node_egomotion "https://github.com/paavansirivardhan123/visiona/blob/main/perception/egomotion.py"
click node_speed "https://github.com/paavansirivardhan123/visiona/blob/main/kinematics/speed.py"
click node_ttc "https://github.com/paavansirivardhan123/visiona/blob/main/kinematics/ttc.py"
click node_detection "https://github.com/paavansirivardhan123/visiona/blob/main/core/detection.py"
click node_priority "https://github.com/paavansirivardhan123/visiona/blob/main/core/priority_queue.py"
click node_heatmap "https://github.com/paavansirivardhan123/visiona/blob/main/kinematics/heatmap.py"
click node_speech "https://github.com/paavansirivardhan123/visiona/blob/main/audio/speech.py"
click node_alert "https://github.com/paavansirivardhan123/visiona/blob/main/audio/alert.py"
click node_voice "https://github.com/paavansirivardhan123/visiona/blob/main/audio/voice_input.py"
click node_agent "https://github.com/paavansirivardhan123/visiona/blob/main/agents/orchestrator.py"
click node_tools "https://github.com/paavansirivardhan123/visiona/blob/main/agents/tools/vision_tools.py"
click node_recognition "https://github.com/paavansirivardhan123/visiona/blob/main/core/recognition.py"
click node_memory "https://github.com/paavansirivardhan123/visiona/blob/main/core/memory.py"
click node_maps "https://github.com/paavansirivardhan123/visiona/blob/main/services/google_maps.py"
click node_vector "https://github.com/paavansirivardhan123/visiona/blob/main/services/vector_db.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_config,node_user toneBlue
class node_vision,node_depth,node_tracker,node_kalman,node_egomotion,node_speed,node_ttc,node_detection toneAmber
class node_priority,node_heatmap,node_speech,node_alert,node_maps_api toneMint
class node_voice,node_agent,node_tools,node_recognition toneRose
class node_memory,node_maps,node_vector,node_cameras toneIndigo
```

## Components

### Capture and orchestration

- [Application loop](https://github.com/paavansirivardhan123/visiona/blob/main/main.py): `main.py`
- [Runtime settings](https://github.com/paavansirivardhan123/visiona/blob/main/core/config.py): `core/config.py`

### Spatial perception

- [Detection pipeline](https://github.com/paavansirivardhan123/visiona/blob/main/perception/vision.py): `perception/vision.py`
- [Monocular depth](https://github.com/paavansirivardhan123/visiona/blob/main/perception/mono_depth.py): `perception/mono_depth.py`
- [Object tracking](https://github.com/paavansirivardhan123/visiona/blob/main/perception/tracker.py): `perception/tracker.py`
- [Depth filtering](https://github.com/paavansirivardhan123/visiona/blob/main/kinematics/kalman.py): `kinematics/kalman.py`
- [User motion](https://github.com/paavansirivardhan123/visiona/blob/main/perception/egomotion.py): `perception/egomotion.py`
- [Object speed](https://github.com/paavansirivardhan123/visiona/blob/main/kinematics/speed.py): `kinematics/speed.py`
- [Collision timing](https://github.com/paavansirivardhan123/visiona/blob/main/kinematics/ttc.py): `kinematics/ttc.py`
- [Spatial records](https://github.com/paavansirivardhan123/visiona/blob/main/core/detection.py): `core/detection.py`

### Threat and audio guidance

- [Threat priority](https://github.com/paavansirivardhan123/visiona/blob/main/core/priority_queue.py): `core/priority_queue.py`
- [Message grouping](https://github.com/paavansirivardhan123/visiona/blob/main/kinematics/heatmap.py): `kinematics/heatmap.py`
- [Speech output](https://github.com/paavansirivardhan123/visiona/blob/main/audio/speech.py): `audio/speech.py`
- [Proximity beeps](https://github.com/paavansirivardhan123/visiona/blob/main/audio/alert.py): `audio/alert.py`

### Voice and reasoning

- [Push-to-talk](https://github.com/paavansirivardhan123/visiona/blob/main/audio/voice_input.py): `audio/voice_input.py`
- [Reasoning router](https://github.com/paavansirivardhan123/visiona/blob/main/agents/orchestrator.py): `agents/orchestrator.py`
- [Assistant tools](https://github.com/paavansirivardhan123/visiona/blob/main/agents/tools/vision_tools.py): `agents/tools/vision_tools.py`
- [Custom recognition](https://github.com/paavansirivardhan123/visiona/blob/main/core/recognition.py): `core/recognition.py`

### Memory and navigation

- [Visual memory and goals](https://github.com/paavansirivardhan123/visiona/blob/main/core/memory.py): `core/memory.py`
- [Walking directions](https://github.com/paavansirivardhan123/visiona/blob/main/services/google_maps.py): `services/google_maps.py`
- [Object signatures](https://github.com/paavansirivardhan123/visiona/blob/main/services/vector_db.py): `services/vector_db.py`

### Other components

- **User**
- **Camera feeds**
- **Google Maps API**

## Connections

- User → Push-to-talk: speaks commands (evidence: `README.md`)
- Camera feeds → Application loop: provide frames (evidence: `README.md`)
- Application loop → Detection pipeline: processes frames (evidence: `main.py`)
- Application loop → Runtime settings: reads settings (evidence: `main.py`)
- Detection pipeline → Monocular depth: estimates distance (evidence: `perception/vision.py`)
- Detection pipeline → Object tracking: tracks detections (evidence: `perception/vision.py`)
- Object tracking → Depth filtering: filters depth (evidence: `perception/tracker.py`)
- Detection pipeline → User motion: estimates user motion (evidence: `perception/vision.py`)
- Detection pipeline → Object speed: estimates speed (evidence: `perception/vision.py`)
- Detection pipeline → Collision timing: computes collision time (evidence: `perception/vision.py`)
- Detection pipeline → Spatial records: creates records (evidence: `perception/vision.py`)
- Application loop → Threat priority: prioritizes detections (evidence: `main.py`)
- Application loop → Message grouping: builds guidance (evidence: `main.py`)
- Application loop → Speech output: queues speech (evidence: `main.py`)
- Application loop → Proximity beeps: triggers alerts (evidence: `main.py`)
- User → Application loop: operates interface (evidence: `README.md`)
- Application loop → Push-to-talk: captures speech (evidence: `main.py`)
- Application loop → Reasoning router: routes commands (evidence: `main.py`)
- Reasoning router → Assistant tools: dispatches tools (evidence: `agents/orchestrator.py`)
- Application loop → Custom recognition: uses recognition (evidence: `main.py`)
- Application loop → Visual memory and goals: updates and checks (evidence: `main.py`)
- Assistant tools → Visual memory and goals: reads and updates (evidence: `agents/tools/vision_tools.py`)
- Assistant tools → Walking directions: requests route (evidence: `agents/tools/vision_tools.py`)
- Assistant tools → Object signatures: queries signatures (evidence: `agents/tools/vision_tools.py`)
- Walking directions → Google Maps API: fetches directions (evidence: `services/google_maps.py`)
- Speech output → User: speaks guidance (evidence: `README.md`)
