# nyarchlinux/nyarchassistant architecture

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

- Interactive diagram: https://gitdiagram.com/nyarchlinux/nyarchassistant
- Repository: https://github.com/nyarchlinux/nyarchassistant

## Overview

Nyarch Assistant is a Linux desktop AI assistant with chat, voice, avatars, tools, document retrieval, and configurable model providers. The main workflow is user input through the application interface to the controller, which runs a model/tool conversation and returns a rich response; optional voice and avatar handling extend that interaction. Other major capabilities include persistent memory, web search, document chat, image generation, scheduled tasks, and remote interfaces. The graph combines documented product capabilities with relationships visible in the supplied excerpts and SOURCE INDEX; unsampled implementation details are not asserted.

Main entry points: [`src/controller.py`](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/controller.py) (Conversation Controller), [`src/window.py`](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/window.py) (Desktop UI), [`src/main.py`](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/main.py) (Application Startup), [`src/tools.py`](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/tools.py) (Tool Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_desktop["Desktop UI<br/>[window.py]"]
  node_entry["Application Startup<br/>[main.py]"]
  node_settings["Settings And Profiles<br/>[settings.py]"]
  node_tasks["Scheduled Tasks<br/>[scheduled_tasks.py]"]
end

subgraph group_conversation["Conversation Runtime"]
  node_controller["Conversation Controller<br/>[controller.py]"]
  node_context["Context Management<br/>[context_manager.py]"]
  node_modes["Modes<br/>[modes.py]"]
  node_memory[("Long-Term Memory")]
end

subgraph group_providers["AI Capabilities"]
  node_llm["Language Models"]
  node_image["Image Generation"]
end

subgraph group_integrations["Tools And Retrieval"]
  node_tools["Tool Registry<br/>[tools.py]"]
  node_extensions["Extensions<br/>[extensions.py]"]
  node_default_tools["Built-in Tools<br/>[default_tools.py]"]
  node_websearch["Web Search<br/>[websearch.py]"]
  node_website_reader["Website Reading<br/>[website_reader.py]"]
  node_rag["Document Retrieval<br/>[rag_handler.py]"]
end

subgraph group_interaction["Voice And Interfaces"]
  node_stt["Speech Recognition"]
  node_tts["Speech Synthesis"]
  node_translator["Translation"]
  node_avatar["Avatar Rendering"]
  node_interfaces["Remote Interfaces"]
end

node_user(("User"))
node_external{{"Model Services"}}

node_user -->|"chats through"| node_desktop
node_desktop -.->|"starts application"| node_entry
node_entry -->|"creates runtime"| node_controller
node_entry -->|"opens window"| node_desktop
node_desktop -.->|"sends interaction"| node_controller
node_settings -->|"configures"| node_controller
node_tasks -->|"runs scheduled chats"| node_controller
node_controller -->|"runs model"| node_llm
node_controller -->|"dispatches tools"| node_tools
node_controller -->|"loads modes"| node_modes
node_controller -.->|"trims context"| node_context
node_controller -->|"uses memory"| node_memory
node_controller -->|"retrieves documents"| node_rag
node_controller -->|"offers search"| node_websearch
node_controller -->|"reads websites"| node_website_reader
node_controller -->|"generates images"| node_image
node_controller -->|"transcribes speech"| node_stt
node_controller -->|"speaks response"| node_tts
node_controller -->|"translates speech"| node_translator
node_controller -->|"drives avatar"| node_avatar
node_controller -->|"loads extensions"| node_extensions
node_extensions -->|"registers tools"| node_tools
node_tools -.->|"exposes built-ins"| node_default_tools
node_interfaces -->|"controls chats"| node_controller
node_llm -.->|"calls providers"| node_external

click node_desktop "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/window.py"
click node_entry "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/main.py"
click node_settings "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/ui/settings.py"
click node_tasks "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/ui/scheduled_tasks.py"
click node_controller "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/controller.py"
click node_context "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/utility/context_manager.py"
click node_modes "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/modes.py"
click node_tools "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/tools.py"
click node_extensions "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/extensions.py"
click node_default_tools "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/integrations/default_tools.py"
click node_websearch "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/integrations/websearch.py"
click node_website_reader "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/integrations/website_reader.py"
click node_rag "https://github.com/nyarchlinux/nyarchassistant/blob/master/src/handlers/rag/rag_handler.py"
click node_memory "https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/memory"
click node_llm "https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/llm"
click node_image "https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/image_generator"
click node_stt "https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/stt"
click node_tts "https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/tts"
click node_translator "https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/translator"
click node_avatar "https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/avatar"
click node_interfaces "https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/interfaces"

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_desktop,node_entry,node_settings,node_tasks,node_user toneBlue
class node_controller,node_context,node_modes,node_memory toneAmber
class node_llm,node_image toneMint
class node_tools,node_extensions,node_default_tools,node_websearch,node_website_reader,node_rag toneRose
class node_stt,node_tts,node_translator,node_avatar,node_interfaces,node_external toneIndigo
```

## Components

### Application

- [Desktop UI](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/window.py): `src/window.py`
- [Application Startup](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/main.py): `src/main.py`
- [Settings And Profiles](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/ui/settings.py): `src/ui/settings.py`
- [Scheduled Tasks](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/ui/scheduled_tasks.py): `src/ui/scheduled_tasks.py`

### Conversation Runtime

- [Conversation Controller](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/controller.py): `src/controller.py`
- [Context Management](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/utility/context_manager.py): `src/utility/context_manager.py`
- [Modes](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/modes.py): `src/modes.py`
- [Long-Term Memory](https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/memory): `src/handlers/memory`

### AI Capabilities

- [Language Models](https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/llm): `src/handlers/llm`
- [Image Generation](https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/image_generator): `src/handlers/image_generator`

### Tools And Retrieval

- [Tool Registry](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/tools.py): `src/tools.py`
- [Extensions](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/extensions.py): `src/extensions.py`
- [Built-in Tools](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/integrations/default_tools.py): `src/integrations/default_tools.py`
- [Web Search](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/integrations/websearch.py): `src/integrations/websearch.py`
- [Website Reading](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/integrations/website_reader.py): `src/integrations/website_reader.py`
- [Document Retrieval](https://github.com/nyarchlinux/nyarchassistant/blob/master/src/handlers/rag/rag_handler.py): `src/handlers/rag/rag_handler.py`

### Voice And Interfaces

- [Speech Recognition](https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/stt): `src/handlers/stt`
- [Speech Synthesis](https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/tts): `src/handlers/tts`
- [Translation](https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/translator): `src/handlers/translator`
- [Avatar Rendering](https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/avatar): `src/handlers/avatar`
- [Remote Interfaces](https://github.com/nyarchlinux/nyarchassistant/tree/master/src/handlers/interfaces): `src/handlers/interfaces`

### Other components

- **User**
- **Model Services**

## Connections

- User → Desktop UI: chats through (evidence: `README.md`)
- Desktop UI → Application Startup: starts application (evidence: `src/main.py`)
- Application Startup → Conversation Controller: creates runtime (evidence: `src/main.py`)
- Application Startup → Desktop UI: opens window (evidence: `src/main.py`)
- Desktop UI → Conversation Controller: sends interaction
- Settings And Profiles → Conversation Controller: configures (evidence: `src/ui/settings.py`)
- Scheduled Tasks → Conversation Controller: runs scheduled chats (evidence: `README.md`)
- Conversation Controller → Language Models: runs model (evidence: `src/controller.py`)
- Conversation Controller → Tool Registry: dispatches tools (evidence: `src/controller.py`)
- Conversation Controller → Modes: loads modes (evidence: `src/controller.py`)
- Conversation Controller → Context Management: trims context (evidence: `src/controller.py`)
- Conversation Controller → Long-Term Memory: uses memory (evidence: `src/controller.py`)
- Conversation Controller → Document Retrieval: retrieves documents (evidence: `src/controller.py`)
- Conversation Controller → Web Search: offers search (evidence: `src/controller.py`)
- Conversation Controller → Website Reading: reads websites (evidence: `README.md`)
- Conversation Controller → Image Generation: generates images (evidence: `src/controller.py`)
- Conversation Controller → Speech Recognition: transcribes speech (evidence: `src/controller.py`)
- Conversation Controller → Speech Synthesis: speaks response (evidence: `src/controller.py`)
- Conversation Controller → Translation: translates speech (evidence: `README.md`)
- Conversation Controller → Avatar Rendering: drives avatar (evidence: `src/controller.py`)
- Conversation Controller → Extensions: loads extensions (evidence: `src/controller.py`)
- Extensions → Tool Registry: registers tools (evidence: `src/extensions.py`)
- Tool Registry → Built-in Tools: exposes built-ins
- Remote Interfaces → Conversation Controller: controls chats (evidence: `src/handlers/interfaces/gui_api_handler.py`)
- Language Models → Model Services: calls providers
