# ouru77/ev-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/ouru77/ev-assistant
- Repository: https://github.com/ouru77/ev-assistant

## Overview

E.V. is a local-first desktop voice assistant. The main workflow runs from the user’s microphone or typed message through the HUD and FastAPI server; speech is transcribed, deterministic commands are routed before the LLM, and replies return to the UI for speech playback. Separate branches provide PC control, memory, web tools, screen vision, and dashboard data. The README documents these capabilities; some server-side wiring is only supported by the source index, so uncertain links are omitted.

Main entry points: [`server.py`](https://github.com/ouru77/ev-assistant/blob/main/server.py) (Assistant server), [`frontend/main.js`](https://github.com/ouru77/ev-assistant/blob/main/frontend/main.js) (Web HUD), [`electron/main.js`](https://github.com/ouru77/ev-assistant/blob/main/electron/main.js) (Electron HUD), [`screen_capture.py`](https://github.com/ouru77/ev-assistant/blob/main/screen_capture.py) (Screen vision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop and UI"]
  node_electron["Electron HUD<br/>[main.js]"]
  node_frontend["Web HUD<br/>[main.js]"]
end

subgraph group_backend["Assistant backend"]
  node_server["Assistant server<br/>[server.py]"]
  node_strings["Bilingual prompts<br/>[strings.py]"]
end

subgraph group_features["Assistant capabilities"]
  node_stt["Whisper STT<br/>[whisper_stt.py]"]
  node_router["Command router<br/>[command_router.py]"]
  node_pc["PC control<br/>[pc_control.py]"]
  node_memory[("Long-term memory<br/>[server.py]")]
  node_webtools["Browser tools<br/>[browser_tools.py]"]
  node_vision["Screen vision<br/>[screen_capture.py]"]
  node_dashboard["Dashboard data<br/>[server.py]"]
end

subgraph group_integrations["Models and services"]
  node_ollama["Ollama LLM"]
  node_anthropic["Anthropic Claude"]
  node_voice["Speech output"]
  node_web["Web services"]
end

node_user(("User"))

node_user -->|"speaks or types"| node_frontend
node_electron -->|"starts and pings"| node_server
node_electron -->|"loads HUD"| node_frontend
node_frontend -->|"sends messages"| node_server
node_frontend -.->|"uploads audio"| node_server
node_server -->|"transcribes audio"| node_stt
node_server -->|"routes commands"| node_router
node_server -->|"uses prompts"| node_strings
node_server -->|"executes actions"| node_pc
node_server -.->|"reads and updates"| node_memory
node_server -->|"runs web actions"| node_webtools
node_server -->|"requests screen description"| node_vision
node_server -->|"serves status data"| node_dashboard
node_server -->|"sends prompts"| node_ollama
node_server -->|"sends prompts"| node_anthropic
node_server -.->|"fetches web content"| node_web
node_vision -->|"submits screenshot"| node_anthropic
node_frontend -->|"speaks replies"| node_voice
node_server -->|"returns responses"| node_frontend

click node_electron "https://github.com/ouru77/ev-assistant/blob/main/electron/main.js"
click node_frontend "https://github.com/ouru77/ev-assistant/blob/main/frontend/main.js"
click node_server "https://github.com/ouru77/ev-assistant/blob/main/server.py"
click node_strings "https://github.com/ouru77/ev-assistant/blob/main/strings.py"
click node_stt "https://github.com/ouru77/ev-assistant/blob/main/whisper_stt.py"
click node_router "https://github.com/ouru77/ev-assistant/blob/main/command_router.py"
click node_pc "https://github.com/ouru77/ev-assistant/blob/main/pc_control.py"
click node_memory "https://github.com/ouru77/ev-assistant/blob/main/server.py"
click node_webtools "https://github.com/ouru77/ev-assistant/blob/main/browser_tools.py"
click node_vision "https://github.com/ouru77/ev-assistant/blob/main/screen_capture.py"
click node_dashboard "https://github.com/ouru77/ev-assistant/blob/main/server.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_electron,node_frontend,node_user toneBlue
class node_server,node_strings toneAmber
class node_stt,node_router,node_pc,node_memory,node_webtools,node_vision,node_dashboard toneMint
class node_ollama,node_anthropic,node_voice,node_web toneRose
```

## Components

### Desktop and UI

- [Electron HUD](https://github.com/ouru77/ev-assistant/blob/main/electron/main.js): `electron/main.js`
- [Web HUD](https://github.com/ouru77/ev-assistant/blob/main/frontend/main.js): `frontend/main.js`

### Assistant backend

- [Assistant server](https://github.com/ouru77/ev-assistant/blob/main/server.py): `server.py`
- [Bilingual prompts](https://github.com/ouru77/ev-assistant/blob/main/strings.py): `strings.py`

### Assistant capabilities

- [Whisper STT](https://github.com/ouru77/ev-assistant/blob/main/whisper_stt.py): `whisper_stt.py`
- [Command router](https://github.com/ouru77/ev-assistant/blob/main/command_router.py): `command_router.py`
- [PC control](https://github.com/ouru77/ev-assistant/blob/main/pc_control.py): `pc_control.py`
- [Long-term memory](https://github.com/ouru77/ev-assistant/blob/main/server.py): `server.py`
- [Browser tools](https://github.com/ouru77/ev-assistant/blob/main/browser_tools.py): `browser_tools.py`
- [Screen vision](https://github.com/ouru77/ev-assistant/blob/main/screen_capture.py): `screen_capture.py`
- [Dashboard data](https://github.com/ouru77/ev-assistant/blob/main/server.py): `server.py`

### Models and services

- **Ollama LLM**
- **Anthropic Claude**
- **Speech output**
- **Web services**

### Other components

- **User**

## Connections

- User → Web HUD: speaks or types (evidence: `README.md`)
- Electron HUD → Assistant server: starts and pings (evidence: `electron/main.js`)
- Electron HUD → Web HUD: loads HUD (evidence: `electron/main.js`)
- Web HUD → Assistant server: sends messages (evidence: `README.md`)
- Web HUD → Assistant server: uploads audio
- Assistant server → Whisper STT: transcribes audio (evidence: `server.py`)
- Assistant server → Command router: routes commands (evidence: `README.md`)
- Assistant server → Bilingual prompts: uses prompts (evidence: `server.py`)
- Assistant server → PC control: executes actions (evidence: `server.py`)
- Assistant server → Long-term memory: reads and updates (evidence: `README.md`)
- Assistant server → Browser tools: runs web actions (evidence: `server.py`)
- Assistant server → Screen vision: requests screen description (evidence: `server.py`)
- Assistant server → Dashboard data: serves status data (evidence: `README.md`)
- Assistant server → Ollama LLM: sends prompts (evidence: `server.py`)
- Assistant server → Anthropic Claude: sends prompts (evidence: `server.py`)
- Assistant server → Web services: fetches web content
- Screen vision → Anthropic Claude: submits screenshot (evidence: `screen_capture.py`)
- Web HUD → Speech output: speaks replies (evidence: `README.md`)
- Assistant server → Web HUD: returns responses (evidence: `README.md`)
