# joshuafernandes-code/guidebot architecture

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

- Interactive diagram: https://gitdiagram.com/joshuafernandes-code/guidebot
- Repository: https://github.com/joshuafernandes-code/guidebot

## Overview

GuideBot is a wearable navigation assistant: an ESP32 streams camera video to a laptop, where the main loop detects objects, estimates their distance and direction, and speaks hazard alerts. Voice commands can query nearby directions or request OCR and face identification. The README documents the streaming workflow and these major capabilities; wiring is based on the sampled main loop and modules, while peripheral hardware details are not shown.

Main entry points: [`main.py`](https://github.com/joshuafernandes-code/guidebot/blob/main/main.py) (Runtime loop), [`pipeline/stream.py`](https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/stream.py) (Frame stream), [`pipeline/depth.py`](https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/depth.py) (Depth estimation), [`audio/voice_input.py`](https://github.com/joshuafernandes-code/guidebot/blob/main/audio/voice_input.py) (Voice commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Video capture"]
  node_esp32["ESP32 stream"]
  node_stream["Frame stream<br/>[stream.py]"]
end

subgraph group_orchestration["Laptop runtime"]
  node_main["Runtime loop<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_perception["Visual processing"]
  node_detector["Object detection<br/>[detection.py]"]
  node_depth["Depth estimation<br/>[depth.py]"]
  node_decision["Hazard decisions<br/>[decision.py]"]
  node_ocr["Text reading<br/>[ocr.py]"]
  node_faces["Face recognition<br/>[face.py]"]
end

subgraph group_interaction["Voice interaction"]
  node_voice["Voice commands<br/>[voice_input.py]"]
  node_tts["Speech output<br/>[tts.py]"]
end

node_camera(("Camera"))
node_user(("Wearer"))
node_speaker(("Audio output"))

node_camera -->|"captures video"| node_esp32
node_esp32 -->|"streams video"| node_stream
node_main -->|"requests frames"| node_stream
node_stream -->|"returns frames"| node_main
node_main -->|"detects objects"| node_detector
node_detector -->|"returns detections"| node_main
node_main -->|"estimates depth"| node_depth
node_depth -->|"returns depth map"| node_main
node_main -->|"samples box distance"| node_depth
node_main -->|"judges hazards"| node_decision
node_main -->|"gets directions"| node_decision
node_main -->|"polls commands"| node_voice
node_user -->|"speaks"| node_voice
node_voice -->|"returns commands"| node_main
node_main -->|"answers queries"| node_decision
node_main -->|"reads frame"| node_ocr
node_main -->|"identifies faces"| node_faces
node_main -->|"queues speech"| node_tts
node_tts -->|"speaks alerts"| node_speaker

click node_esp32 "https://github.com/joshuafernandes-code/guidebot/blob/main/esp32/guidebot_stream/guidebot_stream.ino"
click node_stream "https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/stream.py"
click node_main "https://github.com/joshuafernandes-code/guidebot/blob/main/main.py"
click node_config "https://github.com/joshuafernandes-code/guidebot/blob/main/config.py"
click node_detector "https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/detection.py"
click node_depth "https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/depth.py"
click node_decision "https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/decision.py"
click node_ocr "https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/ocr.py"
click node_faces "https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/face.py"
click node_voice "https://github.com/joshuafernandes-code/guidebot/blob/main/audio/voice_input.py"
click node_tts "https://github.com/joshuafernandes-code/guidebot/blob/main/audio/tts.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_esp32,node_stream toneBlue
class node_main,node_config toneAmber
class node_detector,node_depth,node_decision,node_ocr,node_faces toneMint
class node_voice,node_tts toneRose
class node_camera,node_user,node_speaker toneIndigo
```

## Components

### Video capture

- [ESP32 stream](https://github.com/joshuafernandes-code/guidebot/blob/main/esp32/guidebot_stream/guidebot_stream.ino): `esp32/guidebot_stream/guidebot_stream.ino`
- [Frame stream](https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/stream.py): `pipeline/stream.py`

### Laptop runtime

- [Runtime loop](https://github.com/joshuafernandes-code/guidebot/blob/main/main.py): `main.py`
- [Configuration](https://github.com/joshuafernandes-code/guidebot/blob/main/config.py): `config.py`

### Visual processing

- [Object detection](https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/detection.py): `pipeline/detection.py`
- [Depth estimation](https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/depth.py): `pipeline/depth.py`
- [Hazard decisions](https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/decision.py): `pipeline/decision.py`
- [Text reading](https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/ocr.py): `pipeline/ocr.py`
- [Face recognition](https://github.com/joshuafernandes-code/guidebot/blob/main/pipeline/face.py): `pipeline/face.py`

### Voice interaction

- [Voice commands](https://github.com/joshuafernandes-code/guidebot/blob/main/audio/voice_input.py): `audio/voice_input.py`
- [Speech output](https://github.com/joshuafernandes-code/guidebot/blob/main/audio/tts.py): `audio/tts.py`

### Other components

- **Camera**
- **Wearer**
- **Audio output**

## Connections

- Camera → ESP32 stream: captures video
- ESP32 stream → Frame stream: streams video
- Runtime loop → Frame stream: requests frames
- Frame stream → Runtime loop: returns frames
- Runtime loop → Object detection: detects objects
- Object detection → Runtime loop: returns detections
- Runtime loop → Depth estimation: estimates depth
- Depth estimation → Runtime loop: returns depth map
- Runtime loop → Depth estimation: samples box distance
- Runtime loop → Hazard decisions: judges hazards
- Runtime loop → Hazard decisions: gets directions
- Runtime loop → Voice commands: polls commands
- Wearer → Voice commands: speaks
- Voice commands → Runtime loop: returns commands
- Runtime loop → Hazard decisions: answers queries
- Runtime loop → Text reading: reads frame
- Runtime loop → Face recognition: identifies faces
- Runtime loop → Speech output: queues speech
- Speech output → Audio output: speaks alerts