# ygyg4255-dotcom/ai-desktop-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/ygyg4255-dotcom/ai-desktop-assistant
- Repository: https://github.com/ygyg4255-dotcom/ai-desktop-assistant

## Overview

Altron is a Windows desktop AI assistant. A user interacts through the floating chat UI or voice wake-word; the chat submits requests to the agent, which consults the AI backend and can execute tools, including file operations, desktop-icon control, and PDF reporting. The UI also exposes settings, conversation history, and permission prompts; voice and Telegram provide additional interaction and response channels. The graph follows documented capabilities, but some wiring—especially Telegram command dispatch and voice orchestration—is not visible in the sampled excerpts and is left unverified.

Main entry points: [`src/ui/chat_window.py`](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/ui/chat_window.py) (Chat capsule), [`src/agent/executor.py`](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/executor.py) (Agent loop), [`src/agent/tools.py`](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/tools.py) (Tool registry), [`src/app.py`](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/app.py) (Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_app["Application<br/>[app.py]"]
  node_chat["Chat capsule<br/>[chat_window.py]"]
  node_tray["System tray<br/>[system_tray.py]"]
  node_settings_ui["Settings dialog<br/>[settings_window.py]"]
  node_voice["Voice services<br/>[voice_service.py]"]
end

subgraph group_agent["Agent execution"]
  node_executor["Agent loop<br/>[executor.py]"]
  node_permissions["Permission rules<br/>[permissions.py]"]
  node_tools["Tool registry<br/>[tools.py]"]
  node_file_ops["File operations<br/>[tools.py]"]
  node_reporting["PDF reporting<br/>[tools.py]"]
end

subgraph group_integrations["External capabilities"]
  node_desktop_icons["Desktop icon control"]
  node_ai_client["AI API client<br/>[ai_client.py]"]
  node_omniroute["OmniRoute manager"]
  node_telegram["Telegram service"]
end

subgraph group_state["Configuration and state"]
  node_settings["App settings<br/>[settings.py]"]
  node_database[("SQLite store<br/>[db.py]")]
end

node_user(("Desktop user"))
node_llm{{"LLM endpoint"}}
node_telegram_api{{"Telegram API"}}

node_user -->|"enters requests"| node_chat
node_user -->|"opens controls"| node_tray
node_app -->|"initializes"| node_database
node_app -->|"creates"| node_tray
node_app -->|"creates"| node_chat
node_app -->|"loads"| node_settings
node_chat -->|"submits prompts"| node_executor
node_chat -->|"uses history"| node_database
node_chat -->|"uses voice"| node_voice
node_chat -->|"uses messaging"| node_telegram
node_executor -->|"requests responses"| node_ai_client
node_executor -->|"dispatches tools"| node_tools
node_executor -->|"checks permissions"| node_permissions
node_executor -->|"records executions"| node_database
node_tools -->|"dispatches file actions"| node_file_ops
node_tools -.->|"dispatches reports"| node_reporting
node_tools -->|"controls icons"| node_desktop_icons
node_ai_client -->|"sends API requests"| node_llm
node_omniroute -->|"checks local endpoint"| node_llm
node_telegram -->|"polls and sends"| node_telegram_api
node_settings_ui -->|"edits configuration"| node_settings
node_settings_ui -->|"reads preferences"| node_database
node_settings_ui -->|"configures permissions"| node_tools
node_settings_ui -->|"tests connection"| node_ai_client
node_user -->|"speaks wake word"| node_voice
node_telegram -.->|"delivers remote commands"| node_chat

click node_app "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/app.py"
click node_chat "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/ui/chat_window.py"
click node_tray "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/ui/system_tray.py"
click node_settings_ui "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/ui/settings_window.py"
click node_voice "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/voice_service.py"
click node_executor "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/executor.py"
click node_permissions "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/permissions.py"
click node_tools "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/tools.py"
click node_file_ops "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/tools.py"
click node_reporting "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/tools.py"
click node_desktop_icons "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/desktop_icon_service.py"
click node_ai_client "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/ai_client.py"
click node_omniroute "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/omniroute_manager.py"
click node_telegram "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/telegram_service.py"
click node_settings "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/config/settings.py"
click node_database "https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/storage/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_app,node_chat,node_tray,node_settings_ui,node_voice,node_user toneBlue
class node_executor,node_permissions,node_tools,node_file_ops,node_reporting toneAmber
class node_desktop_icons,node_ai_client,node_omniroute,node_telegram,node_telegram_api toneMint
class node_settings,node_database toneRose
class node_llm toneIndigo
```

## Components

### User interaction

- [Application](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/app.py): `src/app.py`
- [Chat capsule](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/ui/chat_window.py): `src/ui/chat_window.py`
- [System tray](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/ui/system_tray.py): `src/ui/system_tray.py`
- [Settings dialog](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/ui/settings_window.py): `src/ui/settings_window.py`
- [Voice services](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/voice_service.py): `src/services/voice_service.py`

### Agent execution

- [Agent loop](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/executor.py): `src/agent/executor.py`
- [Permission rules](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/permissions.py): `src/agent/permissions.py`
- [Tool registry](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/tools.py): `src/agent/tools.py`
- [File operations](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/tools.py): `src/agent/tools.py`
- [PDF reporting](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/agent/tools.py): `src/agent/tools.py`

### External capabilities

- [Desktop icon control](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/desktop_icon_service.py): `src/services/desktop_icon_service.py`
- [AI API client](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/ai_client.py): `src/services/ai_client.py`
- [OmniRoute manager](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/omniroute_manager.py): `src/services/omniroute_manager.py`
- [Telegram service](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/services/telegram_service.py): `src/services/telegram_service.py`

### Configuration and state

- [App settings](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/config/settings.py): `src/config/settings.py`
- [SQLite store](https://github.com/ygyg4255-dotcom/ai-desktop-assistant/blob/main/src/storage/db.py): `src/storage/db.py`

### Other components

- **Desktop user**
- **LLM endpoint**
- **Telegram API**

## Connections

- Desktop user → Chat capsule: enters requests (evidence: `README.md`)
- Desktop user → System tray: opens controls
- Application → SQLite store: initializes (evidence: `src/app.py`)
- Application → System tray: creates (evidence: `src/app.py`)
- Application → Chat capsule: creates (evidence: `src/app.py`)
- Application → App settings: loads (evidence: `src/app.py`)
- Chat capsule → Agent loop: submits prompts (evidence: `src/ui/chat_window.py`)
- Chat capsule → SQLite store: uses history (evidence: `src/ui/chat_window.py`)
- Chat capsule → Voice services: uses voice (evidence: `src/ui/chat_window.py`)
- Chat capsule → Telegram service: uses messaging (evidence: `src/ui/chat_window.py`)
- Agent loop → AI API client: requests responses (evidence: `src/agent/executor.py`)
- Agent loop → Tool registry: dispatches tools (evidence: `src/agent/executor.py`)
- Agent loop → Permission rules: checks permissions (evidence: `src/agent/executor.py`)
- Agent loop → SQLite store: records executions (evidence: `src/agent/executor.py`)
- Tool registry → File operations: dispatches file actions (evidence: `src/agent/tools.py`)
- Tool registry → PDF reporting: dispatches reports (evidence: `README.md`)
- Tool registry → Desktop icon control: controls icons (evidence: `src/agent/tools.py`)
- AI API client → LLM endpoint: sends API requests (evidence: `src/services/ai_client.py`)
- OmniRoute manager → LLM endpoint: checks local endpoint (evidence: `src/services/omniroute_manager.py`)
- Telegram service → Telegram API: polls and sends (evidence: `src/services/telegram_service.py`)
- Settings dialog → App settings: edits configuration (evidence: `src/ui/settings_window.py`)
- Settings dialog → SQLite store: reads preferences (evidence: `src/ui/settings_window.py`)
- Settings dialog → Tool registry: configures permissions (evidence: `src/ui/settings_window.py`)
- Settings dialog → AI API client: tests connection (evidence: `src/ui/settings_window.py`)
- Desktop user → Voice services: speaks wake word (evidence: `README.md`)
- Telegram service → Chat capsule: delivers remote commands (evidence: `src/ui/chat_window.py`)