# zesaen/voxdrive architecture

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

- Interactive diagram: https://gitdiagram.com/zesaen/voxdrive
- Repository: https://github.com/zesaen/voxdrive
- Video tour (about a minute): https://gitdiagram.com/zesaen/voxdrive/video

## Overview

VoxDrive is a distributed in-vehicle system: RK3588 handles recording and edge voice recognition, while Jetson provides intent routing, vehicle knowledge and tool services, language/vision answers, speech output, and the dashboard. In the voice workflow, RK recognition sends text to Jetson’s router, which classifies it and invokes the relevant RAG, LLM, vehicle-tool, or VLM service; responses can be spoken through TTS and surfaced in the dashboard. The recorder independently captures, encodes, stores, and streams video, exposing status, events, controls, and snapshots across boards. Some subsystem wiring is documented in the README but has no implementation file in the supplied tree; those nodes use only supported paths or null.

Main entry points: [`jetson/services/intent_router/main.cpp`](https://github.com/zesaen/voxdrive/blob/main/jetson/services/intent_router/main.cpp) (Intent Router), [`jetson/dashboard/dashboard_ui.py`](https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/dashboard_ui.py) (Dashboard), [`rk/service/recorder_service.cpp`](https://github.com/zesaen/voxdrive/blob/main/rk/service/recorder_service.cpp) (Recorder Service), [`jetson/services/tool_bus/main.cpp`](https://github.com/zesaen/voxdrive/blob/main/jetson/services/tool_bus/main.cpp) (Tool Bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["RK Edge"]
  node_rk_voice["Edge ASR<br/>[voice_service.py]"]
  node_rk_recorder["Recorder Service"]
  node_video_pipeline["Capture Encode"]
  node_mp4[("Segment Storage")]
  node_rk_tts["Edge TTS"]
end

subgraph group_routing["Query Routing"]
  node_router["Intent Router<br/>[main.cpp]"]
  node_classifier["Query Classifier"]
end

subgraph group_answers["Answer Services"]
  node_rag["Manual RAG<br/>[rag_server.py]"]
  node_vector_store[("Manual Vectors")]
  node_llm["LLM Service<br/>[llm_server.py]"]
  node_vlm["Visual Q&amp;A<br/>[vlm_service.py]"]
  node_tts_gateway["TTS Gateway<br/>[main.cpp]"]
end

subgraph group_vehicle["Vehicle Operations"]
  node_tool_bus["Tool Bus<br/>[main.cpp]"]
  node_vehicle_state[("Vehicle State<br/>[StateManager.h]")]
end

subgraph group_ui["Cabin Interface"]
  node_dashboard["Dashboard<br/>[dashboard_ui.py]"]
  node_dashcam_plugin["Dashcam View<br/>[dashcam.py]"]
  node_vehicle_plugin["Vehicle View<br/>[vehicle.py]"]
  node_status_plugin["Status View<br/>[status.py]"]
end

node_driver(("Driver"))
node_mic(("Microphone"))
node_video_input(("Camera Input"))
node_rtmp["RTMP Stream"]
node_media_server["Media Server"]
node_speaker(("Speaker"))

node_driver -->|"speaks"| node_mic
node_mic -->|"audio"| node_rk_voice
node_rk_voice -->|"recognized text"| node_router
node_router -->|"classifies query"| node_classifier
node_router -->|"manual query"| node_rag
node_rag -->|"searches"| node_vector_store
node_router -->|"query and context"| node_llm
node_llm -->|"answer or tool call"| node_router
node_router -->|"dispatches tool"| node_tool_bus
node_tool_bus -->|"reads and writes"| node_vehicle_state
node_tool_bus -->|"forwards dashcam commands"| node_rk_recorder
node_video_input -->|"video frames"| node_video_pipeline
node_video_pipeline -->|"writes segments"| node_mp4
node_video_pipeline -->|"sends encoded video"| node_rtmp
node_rtmp -->|"publishes stream"| node_media_server
node_rk_recorder -->|"status and events"| node_router
node_router -.->|"visual question"| node_vlm
node_vlm -->|"requests snapshot"| node_rk_recorder
node_vlm -.->|"manages model swap"| node_llm
node_router -->|"sends answer text"| node_tts_gateway
node_tts_gateway -.->|"synthesis request"| node_rk_tts
node_rk_tts -.->|"plays speech"| node_speaker
node_router -->|"publishes speech and query status"| node_dashboard
node_dashboard -->|"hosts"| node_dashcam_plugin
node_dashboard -->|"hosts"| node_vehicle_plugin
node_dashboard -->|"hosts"| node_status_plugin
node_rk_recorder -->|"status and alerts"| node_dashboard
node_tool_bus -->|"state updates"| node_dashboard
node_dashboard -->|"dashcam controls"| node_rk_recorder

click node_rk_voice "https://github.com/zesaen/voxdrive/blob/main/rk/voice/voice_service.py"
click node_rk_recorder "https://github.com/zesaen/voxdrive/blob/main/rk/service/recorder_service.cpp"
click node_video_pipeline "https://github.com/zesaen/voxdrive/blob/main/rk/service/recorder_service.cpp"
click node_mp4 "https://github.com/zesaen/voxdrive/blob/main/rk/service/recorder_service.cpp"
click node_router "https://github.com/zesaen/voxdrive/blob/main/jetson/services/intent_router/main.cpp"
click node_classifier "https://github.com/zesaen/voxdrive/blob/main/jetson/services/intent_router/query_classifier.cpp"
click node_rag "https://github.com/zesaen/voxdrive/blob/main/jetson/services/rag/rag_server.py"
click node_vector_store "https://github.com/zesaen/voxdrive/blob/main/jetson/services/rag/python/vehicle_vector_search.py"
click node_llm "https://github.com/zesaen/voxdrive/blob/main/jetson/services/llm/llm_server.py"
click node_vlm "https://github.com/zesaen/voxdrive/blob/main/jetson/services/vlm/vlm_service.py"
click node_tool_bus "https://github.com/zesaen/voxdrive/blob/main/jetson/services/tool_bus/main.cpp"
click node_vehicle_state "https://github.com/zesaen/voxdrive/blob/main/jetson/services/tool_bus/StateManager.h"
click node_tts_gateway "https://github.com/zesaen/voxdrive/blob/main/jetson/services/tts/tts_server/src/main.cpp"
click node_dashboard "https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/dashboard_ui.py"
click node_dashcam_plugin "https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/plugins/dashcam.py"
click node_vehicle_plugin "https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/plugins/vehicle.py"
click node_status_plugin "https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/plugins/status.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_rk_voice,node_rk_recorder,node_video_pipeline,node_mp4,node_rk_tts toneBlue
class node_router,node_classifier toneAmber
class node_rag,node_vector_store,node_llm,node_vlm,node_tts_gateway,node_media_server toneMint
class node_tool_bus,node_vehicle_state toneRose
class node_dashboard,node_dashcam_plugin,node_vehicle_plugin,node_status_plugin,node_driver,node_mic,node_video_input,node_rtmp,node_speaker toneIndigo
```

## Components

### RK Edge

- [Edge ASR](https://github.com/zesaen/voxdrive/blob/main/rk/voice/voice_service.py): `rk/voice/voice_service.py`
- [Recorder Service](https://github.com/zesaen/voxdrive/blob/main/rk/service/recorder_service.cpp): `rk/service/recorder_service.cpp`
- [Capture Encode](https://github.com/zesaen/voxdrive/blob/main/rk/service/recorder_service.cpp): `rk/service/recorder_service.cpp`
- [Segment Storage](https://github.com/zesaen/voxdrive/blob/main/rk/service/recorder_service.cpp): `rk/service/recorder_service.cpp`
- **Edge TTS**

### Query Routing

- [Intent Router](https://github.com/zesaen/voxdrive/blob/main/jetson/services/intent_router/main.cpp): `jetson/services/intent_router/main.cpp`
- [Query Classifier](https://github.com/zesaen/voxdrive/blob/main/jetson/services/intent_router/query_classifier.cpp): `jetson/services/intent_router/query_classifier.cpp`

### Answer Services

- [Manual RAG](https://github.com/zesaen/voxdrive/blob/main/jetson/services/rag/rag_server.py): `jetson/services/rag/rag_server.py`
- [Manual Vectors](https://github.com/zesaen/voxdrive/blob/main/jetson/services/rag/python/vehicle_vector_search.py): `jetson/services/rag/python/vehicle_vector_search.py`
- [LLM Service](https://github.com/zesaen/voxdrive/blob/main/jetson/services/llm/llm_server.py): `jetson/services/llm/llm_server.py`
- [Visual Q&A](https://github.com/zesaen/voxdrive/blob/main/jetson/services/vlm/vlm_service.py): `jetson/services/vlm/vlm_service.py`
- [TTS Gateway](https://github.com/zesaen/voxdrive/blob/main/jetson/services/tts/tts_server/src/main.cpp): `jetson/services/tts/tts_server/src/main.cpp`

### Vehicle Operations

- [Tool Bus](https://github.com/zesaen/voxdrive/blob/main/jetson/services/tool_bus/main.cpp): `jetson/services/tool_bus/main.cpp`
- [Vehicle State](https://github.com/zesaen/voxdrive/blob/main/jetson/services/tool_bus/StateManager.h): `jetson/services/tool_bus/StateManager.h`

### Cabin Interface

- [Dashboard](https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/dashboard_ui.py): `jetson/dashboard/dashboard_ui.py`
- [Dashcam View](https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/plugins/dashcam.py): `jetson/dashboard/plugins/dashcam.py`
- [Vehicle View](https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/plugins/vehicle.py): `jetson/dashboard/plugins/vehicle.py`
- [Status View](https://github.com/zesaen/voxdrive/blob/main/jetson/dashboard/plugins/status.py): `jetson/dashboard/plugins/status.py`

### Other components

- **Driver**
- **Microphone**
- **Camera Input**
- **RTMP Stream**
- **Media Server**
- **Speaker**

## Connections

- Driver → Microphone: speaks
- Microphone → Edge ASR: audio
- Edge ASR → Intent Router: recognized text
- Intent Router → Query Classifier: classifies query
- Intent Router → Manual RAG: manual query
- Manual RAG → Manual Vectors: searches
- Intent Router → LLM Service: query and context
- LLM Service → Intent Router: answer or tool call
- Intent Router → Tool Bus: dispatches tool
- Tool Bus → Vehicle State: reads and writes
- Tool Bus → Recorder Service: forwards dashcam commands
- Camera Input → Capture Encode: video frames
- Capture Encode → Segment Storage: writes segments
- Capture Encode → RTMP Stream: sends encoded video
- RTMP Stream → Media Server: publishes stream
- Recorder Service → Intent Router: status and events
- Intent Router → Visual Q&A: visual question
- Visual Q&A → Recorder Service: requests snapshot
- Visual Q&A → LLM Service: manages model swap
- Intent Router → TTS Gateway: sends answer text
- TTS Gateway → Edge TTS: synthesis request
- Edge TTS → Speaker: plays speech
- Intent Router → Dashboard: publishes speech and query status
- Dashboard → Dashcam View: hosts
- Dashboard → Vehicle View: hosts
- Dashboard → Status View: hosts
- Recorder Service → Dashboard: status and alerts
- Tool Bus → Dashboard: state updates
- Dashboard → Recorder Service: dashcam controls