# tanushvasupalli/va architecture

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

- Interactive diagram: https://gitdiagram.com/tanushvasupalli/va
- Repository: https://github.com/tanushvasupalli/va

## Overview

Wednesday is a voice and remote-control AI assistant, with both a local microphone loop and a Telegram control center. Users speak or send text/voice; the assistant transcribes and interprets input, responds with text or speech, and can invoke memory, automation, device, and PC capabilities. A web dashboard provides another interaction and management surface. The graph preserves documented capabilities, but several tool implementations and runtime routes were not excerpted, so uncertain links are omitted or marked dashed.

Main entry points: [`core/brain.py`](https://github.com/tanushvasupalli/va/blob/main/core/brain.py) (Reasoning Brain), [`main.py`](https://github.com/tanushvasupalli/va/blob/main/main.py) (Voice Loop), [`core/telegram_bot.py`](https://github.com/tanushvasupalli/va/blob/main/core/telegram_bot.py) (Telegram Bot), [`core/mcp_client.py`](https://github.com/tanushvasupalli/va/blob/main/core/mcp_client.py) (MCP Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interfaces"]
  node_telegram["Telegram Bot<br/>[telegram_bot.py]"]
  node_dashboard["Web Dashboard<br/>[app.py]"]
end

subgraph group_voice["Voice Processing"]
  node_voice_loop["Voice Loop<br/>[main.py]"]
  node_audio["Microphone Audio<br/>[audio_io.py]"]
  node_vad["Speech Segmentation<br/>[vad.py]"]
  node_wake["Wake Word<br/>[wake_word.py]"]
  node_transcription["Transcription<br/>[transcriber.py]"]
  node_identity["Speaker Recognition"]
  node_speech["Speech Output<br/>[speaker.py]"]
end

subgraph group_intelligence["Assistant Intelligence"]
  node_brain["Reasoning Brain<br/>[brain.py]"]
  node_security["Security Controls<br/>[security.py]"]
end

subgraph group_capabilities["Tools and Integrations"]
  node_automation["n8n Workflows<br/>[n8n_tools.py]"]
  node_mcp["MCP Client<br/>[mcp_client.py]"]
  node_pc_tools["PC Access<br/>[pc_bridge_tools.py]"]
  node_pc_agent["PC Companion<br/>[pc_companion.py]"]
  node_network["Network Tools<br/>[network_tools.py]"]
  node_system["System Tools<br/>[system_tools.py]"]
  node_other_tools["Web, Files, Vision"]
end

subgraph group_state["State and Configuration"]
  node_memory_tools["Memory Tools<br/>[memory_tools.py]"]
  node_storage["Conversation Storage<br/>[storage.py]"]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_config_manager["Config Manager<br/>[config_manager.py]"]
end

node_user(("User"))
node_supabase[("Supabase")]
node_models["Gemini / Groq"]
node_mcp_servers["MCP Servers"]
node_n8n_service["n8n Service"]

node_user -->|"sends messages"| node_telegram
node_user -->|"speaks to"| node_voice_loop
node_user -->|"uses"| node_dashboard
node_voice_loop -->|"starts capture"| node_audio
node_audio -->|"provides chunks"| node_vad
node_voice_loop -->|"records speech"| node_vad
node_voice_loop -.->|"checks wake phrase"| node_wake
node_voice_loop -.->|"transcribes audio"| node_transcription
node_voice_loop -->|"identifies speaker"| node_identity
node_voice_loop -->|"submits query"| node_brain
node_brain -->|"returns spoken reply"| node_speech
node_telegram -->|"submits requests"| node_brain
node_telegram -->|"sends audio replies"| node_speech
node_dashboard -->|"submits text"| node_brain
node_brain -->|"queries models"| node_models
node_brain -->|"reads and writes"| node_storage
node_memory_tools -->|"accesses memories"| node_storage
node_storage -->|"persists data"| node_supabase
node_brain -->|"dispatches workflows"| node_automation
node_automation -->|"calls workflows"| node_n8n_service
node_brain -->|"dispatches MCP tools"| node_mcp
node_mcp -->|"discovers and calls"| node_mcp_servers
node_brain -.->|"dispatches PC actions"| node_pc_tools
node_pc_tools -.->|"requests PC access"| node_pc_agent
node_brain -.->|"dispatches network actions"| node_network
node_brain -->|"dispatches system actions"| node_system
node_brain -.->|"uses assistant tools"| node_other_tools
node_brain -->|"verifies protected actions"| node_security
node_config_manager -->|"refreshes tool discovery"| node_mcp
node_config_manager -->|"updates settings"| node_config

click node_telegram "https://github.com/tanushvasupalli/va/blob/main/core/telegram_bot.py"
click node_dashboard "https://github.com/tanushvasupalli/va/blob/main/dashboard/app.py"
click node_voice_loop "https://github.com/tanushvasupalli/va/blob/main/main.py"
click node_audio "https://github.com/tanushvasupalli/va/blob/main/core/audio_io.py"
click node_vad "https://github.com/tanushvasupalli/va/blob/main/core/vad.py"
click node_wake "https://github.com/tanushvasupalli/va/blob/main/core/wake_word.py"
click node_transcription "https://github.com/tanushvasupalli/va/blob/main/core/transcriber.py"
click node_identity "https://github.com/tanushvasupalli/va/blob/main/core/speaker_recognition.py"
click node_speech "https://github.com/tanushvasupalli/va/blob/main/core/speaker.py"
click node_brain "https://github.com/tanushvasupalli/va/blob/main/core/brain.py"
click node_security "https://github.com/tanushvasupalli/va/blob/main/core/security.py"
click node_automation "https://github.com/tanushvasupalli/va/blob/main/tools/n8n_tools.py"
click node_mcp "https://github.com/tanushvasupalli/va/blob/main/core/mcp_client.py"
click node_pc_tools "https://github.com/tanushvasupalli/va/blob/main/tools/pc_bridge_tools.py"
click node_pc_agent "https://github.com/tanushvasupalli/va/blob/main/pc_companion.py"
click node_network "https://github.com/tanushvasupalli/va/blob/main/tools/network_tools.py"
click node_system "https://github.com/tanushvasupalli/va/blob/main/tools/system_tools.py"
click node_other_tools "https://github.com/tanushvasupalli/va/tree/main/tools"
click node_memory_tools "https://github.com/tanushvasupalli/va/blob/main/tools/memory_tools.py"
click node_storage "https://github.com/tanushvasupalli/va/blob/main/core/storage.py"
click node_config "https://github.com/tanushvasupalli/va/blob/main/config.py"
click node_config_manager "https://github.com/tanushvasupalli/va/blob/main/core/config_manager.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_telegram,node_dashboard,node_user toneBlue
class node_voice_loop,node_audio,node_vad,node_wake,node_transcription,node_identity,node_speech,node_supabase toneAmber
class node_brain,node_security,node_mcp_servers toneMint
class node_automation,node_mcp,node_pc_tools,node_pc_agent,node_network,node_system,node_other_tools toneRose
class node_memory_tools,node_storage,node_config,node_config_manager,node_models,node_n8n_service toneIndigo
```

## Components

### User Interfaces

- [Telegram Bot](https://github.com/tanushvasupalli/va/blob/main/core/telegram_bot.py): `core/telegram_bot.py`
- [Web Dashboard](https://github.com/tanushvasupalli/va/blob/main/dashboard/app.py): `dashboard/app.py`

### Voice Processing

- [Voice Loop](https://github.com/tanushvasupalli/va/blob/main/main.py): `main.py`
- [Microphone Audio](https://github.com/tanushvasupalli/va/blob/main/core/audio_io.py): `core/audio_io.py`
- [Speech Segmentation](https://github.com/tanushvasupalli/va/blob/main/core/vad.py): `core/vad.py`
- [Wake Word](https://github.com/tanushvasupalli/va/blob/main/core/wake_word.py): `core/wake_word.py`
- [Transcription](https://github.com/tanushvasupalli/va/blob/main/core/transcriber.py): `core/transcriber.py`
- [Speaker Recognition](https://github.com/tanushvasupalli/va/blob/main/core/speaker_recognition.py): `core/speaker_recognition.py`
- [Speech Output](https://github.com/tanushvasupalli/va/blob/main/core/speaker.py): `core/speaker.py`

### Assistant Intelligence

- [Reasoning Brain](https://github.com/tanushvasupalli/va/blob/main/core/brain.py): `core/brain.py`
- [Security Controls](https://github.com/tanushvasupalli/va/blob/main/core/security.py): `core/security.py`

### Tools and Integrations

- [n8n Workflows](https://github.com/tanushvasupalli/va/blob/main/tools/n8n_tools.py): `tools/n8n_tools.py`
- [MCP Client](https://github.com/tanushvasupalli/va/blob/main/core/mcp_client.py): `core/mcp_client.py`
- [PC Access](https://github.com/tanushvasupalli/va/blob/main/tools/pc_bridge_tools.py): `tools/pc_bridge_tools.py`
- [PC Companion](https://github.com/tanushvasupalli/va/blob/main/pc_companion.py): `pc_companion.py`
- [Network Tools](https://github.com/tanushvasupalli/va/blob/main/tools/network_tools.py): `tools/network_tools.py`
- [System Tools](https://github.com/tanushvasupalli/va/blob/main/tools/system_tools.py): `tools/system_tools.py`
- [Web, Files, Vision](https://github.com/tanushvasupalli/va/tree/main/tools): `tools`

### State and Configuration

- [Memory Tools](https://github.com/tanushvasupalli/va/blob/main/tools/memory_tools.py): `tools/memory_tools.py`
- [Conversation Storage](https://github.com/tanushvasupalli/va/blob/main/core/storage.py): `core/storage.py`
- [Runtime Configuration](https://github.com/tanushvasupalli/va/blob/main/config.py): `config.py`
- [Config Manager](https://github.com/tanushvasupalli/va/blob/main/core/config_manager.py): `core/config_manager.py`

### Other components

- **User**
- **Supabase**
- **Gemini / Groq**
- **MCP Servers**
- **n8n Service**

## Connections

- User → Telegram Bot: sends messages (evidence: `README.md`)
- User → Voice Loop: speaks to (evidence: `README.md`)
- User → Web Dashboard: uses (evidence: `README.md`)
- Voice Loop → Microphone Audio: starts capture (evidence: `main.py`)
- Microphone Audio → Speech Segmentation: provides chunks (evidence: `core/vad.py`)
- Voice Loop → Speech Segmentation: records speech (evidence: `main.py`)
- Voice Loop → Wake Word: checks wake phrase (evidence: `main.py`)
- Voice Loop → Transcription: transcribes audio (evidence: `main.py`)
- Voice Loop → Speaker Recognition: identifies speaker (evidence: `main.py`)
- Voice Loop → Reasoning Brain: submits query (evidence: `main.py`)
- Reasoning Brain → Speech Output: returns spoken reply (evidence: `main.py`)
- Telegram Bot → Reasoning Brain: submits requests (evidence: `README.md`)
- Telegram Bot → Speech Output: sends audio replies (evidence: `README.md`)
- Web Dashboard → Reasoning Brain: submits text (evidence: `dashboard/app.py`)
- Reasoning Brain → Gemini / Groq: queries models (evidence: `core/brain.py`)
- Reasoning Brain → Conversation Storage: reads and writes (evidence: `core/brain.py`)
- Memory Tools → Conversation Storage: accesses memories (evidence: `tools/memory_tools.py`)
- Conversation Storage → Supabase: persists data (evidence: `core/storage.py`)
- Reasoning Brain → n8n Workflows: dispatches workflows (evidence: `core/brain.py`)
- n8n Workflows → n8n Service: calls workflows (evidence: `README.md`)
- Reasoning Brain → MCP Client: dispatches MCP tools (evidence: `core/brain.py`)
- MCP Client → MCP Servers: discovers and calls (evidence: `core/mcp_client.py`)
- Reasoning Brain → PC Access: dispatches PC actions (evidence: `core/brain.py`)
- PC Access → PC Companion: requests PC access
- Reasoning Brain → Network Tools: dispatches network actions (evidence: `core/brain.py`)
- Reasoning Brain → System Tools: dispatches system actions (evidence: `core/brain.py`)
- Reasoning Brain → Web, Files, Vision: uses assistant tools (evidence: `core/brain.py`)
- Reasoning Brain → Security Controls: verifies protected actions (evidence: `core/brain.py`)
- Config Manager → MCP Client: refreshes tool discovery (evidence: `core/config_manager.py`)
- Config Manager → Runtime Configuration: updates settings (evidence: `core/config_manager.py`)
