# qwersyk/newelle architecture

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

- Interactive diagram: https://gitdiagram.com/qwersyk/newelle
- Repository: https://github.com/qwersyk/newelle

## Overview

Newelle is a desktop virtual assistant: users chat through its interface and can extend conversations with model providers, tools, documents, web search, voice, and image generation. The controller is the central orchestration layer, while handler families implement provider-backed capabilities and utilities support context, media, downloads, and local models. The README documents product features; source excerpts and the SOURCE INDEX establish only some implementation relationships, so uncertain links are omitted or marked unverified.

Main entry points: [`src/controller.py`](https://github.com/qwersyk/newelle/blob/master/src/controller.py) (Conversation controller), [`src/tools.py`](https://github.com/qwersyk/newelle/blob/master/src/tools.py) (Tools and skills), [`src/utility`](https://github.com/qwersyk/newelle/tree/master/src/utility) (Runtime utilities), [`src/window.py`](https://github.com/qwersyk/newelle/blob/master/src/window.py) (Desktop interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["Application startup<br/>[main.py]"]
  node_ui["Desktop interface<br/>[window.py]"]
  node_controller["Conversation controller<br/>[controller.py]"]
  node_interfaces["External interfaces"]
  node_profiles["Modes and profiles<br/>[modes.py]"]
end

subgraph group_ai["AI and content"]
  node_llm["Language models"]
  node_voice["Speech input/output"]
  node_image["Image generation"]
  node_rag["Document retrieval<br/>[rag_handler.py]"]
  node_memory["Conversation memory"]
  node_search["Web search"]
end

subgraph group_extensions["Tools and integrations"]
  node_tools["Tools and skills<br/>[tools.py]"]
  node_integrations["Integration features"]
  node_extensions_loader["Extensions<br/>[extensions.py]"]
end

subgraph group_support["Runtime support"]
  node_context["Context management<br/>[context_manager.py]"]
  node_utilities["Runtime utilities"]
  node_downloads[("Download registry")]
  node_model_library["Local model library<br/>[model_library.py]"]
end

node_user(("User"))

node_user -->|"chats through"| node_ui
node_main -->|"initializes"| node_controller
node_ui -.->|"submits chat"| node_controller
node_controller -->|"selects handlers"| node_llm
node_controller -->|"builds and queries"| node_rag
node_controller -.->|"manages context"| node_context
node_controller -.->|"uses memory"| node_memory
node_controller -->|"updates tools"| node_tools
node_controller -->|"selects handlers"| node_search
node_controller -->|"selects handlers"| node_image
node_controller -.->|"supports voice"| node_voice
node_controller -->|"loads modes"| node_profiles
node_interfaces -.->|"routes API requests"| node_controller
node_integrations -.->|"provides tools"| node_tools
node_extensions_loader -.->|"extends capabilities"| node_tools
node_model_library -->|"tracks transfers"| node_downloads
node_llm -.->|"uses runtime support"| node_utilities
node_voice -.->|"uses runtime support"| node_utilities
node_image -.->|"uses runtime support"| node_utilities

click node_main "https://github.com/qwersyk/newelle/blob/master/src/main.py"
click node_ui "https://github.com/qwersyk/newelle/blob/master/src/window.py"
click node_controller "https://github.com/qwersyk/newelle/blob/master/src/controller.py"
click node_interfaces "https://github.com/qwersyk/newelle/tree/master/src/handlers/interfaces"
click node_profiles "https://github.com/qwersyk/newelle/blob/master/src/modes.py"
click node_llm "https://github.com/qwersyk/newelle/tree/master/src/handlers/llm"
click node_voice "https://github.com/qwersyk/newelle/tree/master/src/handlers/stt"
click node_image "https://github.com/qwersyk/newelle/tree/master/src/handlers/image_generator"
click node_rag "https://github.com/qwersyk/newelle/blob/master/src/handlers/rag/rag_handler.py"
click node_memory "https://github.com/qwersyk/newelle/tree/master/src/handlers/memory"
click node_search "https://github.com/qwersyk/newelle/tree/master/src/handlers/websearch"
click node_tools "https://github.com/qwersyk/newelle/blob/master/src/tools.py"
click node_integrations "https://github.com/qwersyk/newelle/tree/master/src/integrations"
click node_extensions_loader "https://github.com/qwersyk/newelle/blob/master/src/extensions.py"
click node_context "https://github.com/qwersyk/newelle/blob/master/src/utility/context_manager.py"
click node_utilities "https://github.com/qwersyk/newelle/tree/master/src/utility"
click node_downloads "https://github.com/qwersyk/newelle/blob/master/src/utility/download_manager.py"
click node_model_library "https://github.com/qwersyk/newelle/blob/master/src/ui/model_library.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_main,node_ui,node_controller,node_interfaces,node_profiles,node_user toneBlue
class node_llm,node_voice,node_image,node_rag,node_memory,node_search toneAmber
class node_tools,node_integrations,node_extensions_loader toneMint
class node_context,node_utilities,node_downloads,node_model_library toneRose
```

## Components

### Application

- [Application startup](https://github.com/qwersyk/newelle/blob/master/src/main.py): `src/main.py`
- [Desktop interface](https://github.com/qwersyk/newelle/blob/master/src/window.py): `src/window.py`
- [Conversation controller](https://github.com/qwersyk/newelle/blob/master/src/controller.py): `src/controller.py`
- [External interfaces](https://github.com/qwersyk/newelle/tree/master/src/handlers/interfaces): `src/handlers/interfaces`
- [Modes and profiles](https://github.com/qwersyk/newelle/blob/master/src/modes.py): `src/modes.py`

### AI and content

- [Language models](https://github.com/qwersyk/newelle/tree/master/src/handlers/llm): `src/handlers/llm`
- [Speech input/output](https://github.com/qwersyk/newelle/tree/master/src/handlers/stt): `src/handlers/stt`
- [Image generation](https://github.com/qwersyk/newelle/tree/master/src/handlers/image_generator): `src/handlers/image_generator`
- [Document retrieval](https://github.com/qwersyk/newelle/blob/master/src/handlers/rag/rag_handler.py): `src/handlers/rag/rag_handler.py`
- [Conversation memory](https://github.com/qwersyk/newelle/tree/master/src/handlers/memory): `src/handlers/memory`
- [Web search](https://github.com/qwersyk/newelle/tree/master/src/handlers/websearch): `src/handlers/websearch`

### Tools and integrations

- [Tools and skills](https://github.com/qwersyk/newelle/blob/master/src/tools.py): `src/tools.py`
- [Integration features](https://github.com/qwersyk/newelle/tree/master/src/integrations): `src/integrations`
- [Extensions](https://github.com/qwersyk/newelle/blob/master/src/extensions.py): `src/extensions.py`

### Runtime support

- [Context management](https://github.com/qwersyk/newelle/blob/master/src/utility/context_manager.py): `src/utility/context_manager.py`
- [Runtime utilities](https://github.com/qwersyk/newelle/tree/master/src/utility): `src/utility`
- [Download registry](https://github.com/qwersyk/newelle/blob/master/src/utility/download_manager.py): `src/utility/download_manager.py`
- [Local model library](https://github.com/qwersyk/newelle/blob/master/src/ui/model_library.py): `src/ui/model_library.py`

### Other components

- **User**

## Connections

- User → Desktop interface: chats through
- Application startup → Conversation controller: initializes (evidence: `src/main.py`)
- Desktop interface → Conversation controller: submits chat
- Conversation controller → Language models: selects handlers (evidence: `src/controller.py`)
- Conversation controller → Document retrieval: builds and queries (evidence: `src/controller.py`)
- Conversation controller → Context management: manages context (evidence: `src/controller.py`)
- Conversation controller → Conversation memory: uses memory (evidence: `src/controller.py`)
- Conversation controller → Tools and skills: updates tools (evidence: `src/controller.py`)
- Conversation controller → Web search: selects handlers (evidence: `src/controller.py`)
- Conversation controller → Image generation: selects handlers (evidence: `src/controller.py`)
- Conversation controller → Speech input/output: supports voice (evidence: `src/controller.py`)
- Conversation controller → Modes and profiles: loads modes (evidence: `src/controller.py`)
- External interfaces → Conversation controller: routes API requests (evidence: `src/controller.py`)
- Integration features → Tools and skills: provides tools (evidence: `src/integrations/websearch.py`)
- Extensions → Tools and skills: extends capabilities
- Local model library → Download registry: tracks transfers (evidence: `src/ui/model_library.py`)
- Language models → Runtime utilities: uses runtime support (evidence: `src/handlers/llm/llama_cpp_handler.py`)
- Speech input/output → Runtime utilities: uses runtime support (evidence: `src/handlers/stt/whispercpp_handler.py`)
- Image generation → Runtime utilities: uses runtime support (evidence: `src/handlers/image_generator/stablediffusion_cpp_handler.py`)
