# rufulosium/desktop-assistent architecture

> Architecture diagram of the GitHub repository rufulosium/desktop-assistent, 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/rufulosium/desktop-assistent
- Repository: https://github.com/rufulosium/desktop-assistent

## Overview

Desktop Assistant is a voice-first macOS assistant with a permission-gated agent path and a notch-native interface. The main workflow begins with wake-word activation, captures speech, transcribes and routes it to an LLM or agent, then reflects activity in the UI. The graph also preserves documented audio effects, notifications, and provider choices. Some relationships come from README statements and the SOURCE INDEX; unsampled implementation details are not inferred, and the TTS implementation is not present in the supplied tree.

Main entry points: [`src/assistant/pipeline.py`](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/pipeline.py) (Assistant Pipeline), [`src/assistant/app.py`](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/app.py) (App Lifecycle), [`src/assistant/audio/capture.py`](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/capture.py) (Audio Capture), [`src/assistant/ui/island_view.py`](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/ui/island_view.py) (Notch Island UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application Runtime"]
  node_app["App Lifecycle<br/>[app.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_pipeline["Assistant Pipeline<br/>[pipeline.py]"]
end

subgraph group_audio["Audio and Speech"]
  node_capture["Audio Capture<br/>[capture.py]"]
  node_ringbuffer["Audio Ring Buffer<br/>[ringbuffer.py]"]
  node_native_ringbuffer["Native Ring Buffer<br/>[ringbuffer.h]"]
  node_vad["Voice Activity Detection<br/>[vad.py]"]
  node_wake["Wake Detection<br/>[sherpa_engine.py]"]
  node_stt["Speech Recognition<br/>[__init__.py]"]
end

subgraph group_intelligence["Language and Tasks"]
  node_router["Request Router<br/>[classifier.py]"]
  node_llm_local["Local LLM<br/>[local.py]"]
  node_llm_remote["Remote LLM<br/>[remote.py]"]
  node_agent["Agent Dispatch<br/>[dispatch.py]"]
end

subgraph group_experience["Mac Experience"]
  node_island["Notch Island UI<br/>[island_view.py]"]
  node_window["Island Window<br/>[island_window.py]"]
  node_sounds["Sound Effects<br/>[sounds.py]"]
  node_notify["Notifications<br/>[notify.py]"]
end

node_user(("User"))

node_user -->|"starts assistant"| node_app
node_app -->|"uses settings"| node_config
node_app -->|"creates and initializes"| node_pipeline
node_app -->|"initializes UI"| node_window
node_pipeline -->|"runs wake detection"| node_wake
node_pipeline -->|"starts capture"| node_capture
node_capture -->|"uses buffer"| node_ringbuffer
node_capture -->|"uses VAD"| node_vad
node_pipeline -->|"transcribes audio"| node_stt
node_pipeline -->|"routes request"| node_router
node_pipeline -->|"requests completion"| node_llm_local
node_pipeline -->|"requests completion"| node_llm_remote
node_pipeline -->|"dispatches tasks"| node_agent
node_pipeline -->|"plays effects"| node_sounds
node_pipeline -->|"sends notifications"| node_notify
node_pipeline -->|"updates UI state"| node_island
node_window -->|"hosts view"| node_island
node_user -.->|"drops files"| node_island
node_pipeline -->|"checks permissions"| node_config
node_llm_local -.->|"uses local model service"| node_user
node_llm_remote -.->|"uses provider API"| node_user

click node_app "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/app.py"
click node_config "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/config.py"
click node_pipeline "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/pipeline.py"
click node_capture "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/capture.py"
click node_ringbuffer "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/ringbuffer.py"
click node_native_ringbuffer "https://github.com/rufulosium/desktop-assistent/blob/main/native/ringbuffer/ringbuffer.h"
click node_vad "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/vad.py"
click node_wake "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/wake/sherpa_engine.py"
click node_stt "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/stt/__init__.py"
click node_router "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/router/classifier.py"
click node_llm_local "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/llm/local.py"
click node_llm_remote "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/llm/remote.py"
click node_agent "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/agent/dispatch.py"
click node_island "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/ui/island_view.py"
click node_window "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/ui/island_window.py"
click node_sounds "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/sounds.py"
click node_notify "https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/notify.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_config,node_pipeline,node_user toneBlue
class node_capture,node_ringbuffer,node_native_ringbuffer,node_vad,node_wake,node_stt toneAmber
class node_router,node_llm_local,node_llm_remote,node_agent toneMint
class node_island,node_window,node_sounds,node_notify toneRose
```

## Components

### Application Runtime

- [App Lifecycle](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/app.py): `src/assistant/app.py`
- [Configuration](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/config.py): `src/assistant/config.py`
- [Assistant Pipeline](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/pipeline.py): `src/assistant/pipeline.py`

### Audio and Speech

- [Audio Capture](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/capture.py): `src/assistant/audio/capture.py`
- [Audio Ring Buffer](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/ringbuffer.py): `src/assistant/audio/ringbuffer.py`
- [Native Ring Buffer](https://github.com/rufulosium/desktop-assistent/blob/main/native/ringbuffer/ringbuffer.h): `native/ringbuffer/ringbuffer.h`
- [Voice Activity Detection](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/vad.py): `src/assistant/audio/vad.py`
- [Wake Detection](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/wake/sherpa_engine.py): `src/assistant/wake/sherpa_engine.py`
- [Speech Recognition](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/stt/__init__.py): `src/assistant/stt/__init__.py`

### Language and Tasks

- [Request Router](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/router/classifier.py): `src/assistant/router/classifier.py`
- [Local LLM](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/llm/local.py): `src/assistant/llm/local.py`
- [Remote LLM](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/llm/remote.py): `src/assistant/llm/remote.py`
- [Agent Dispatch](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/agent/dispatch.py): `src/assistant/agent/dispatch.py`

### Mac Experience

- [Notch Island UI](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/ui/island_view.py): `src/assistant/ui/island_view.py`
- [Island Window](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/ui/island_window.py): `src/assistant/ui/island_window.py`
- [Sound Effects](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/audio/sounds.py): `src/assistant/audio/sounds.py`
- [Notifications](https://github.com/rufulosium/desktop-assistent/blob/main/src/assistant/notify.py): `src/assistant/notify.py`

### Other components

- **User**

## Connections

- User → App Lifecycle: starts assistant (evidence: `README.md`)
- App Lifecycle → Configuration: uses settings (evidence: `src/assistant/app.py`)
- App Lifecycle → Assistant Pipeline: creates and initializes (evidence: `src/assistant/app.py`)
- App Lifecycle → Island Window: initializes UI (evidence: `src/assistant/app.py`)
- Assistant Pipeline → Wake Detection: runs wake detection (evidence: `src/assistant/pipeline.py`)
- Assistant Pipeline → Audio Capture: starts capture (evidence: `src/assistant/pipeline.py`)
- Audio Capture → Audio Ring Buffer: uses buffer (evidence: `src/assistant/audio/capture.py`)
- Audio Capture → Voice Activity Detection: uses VAD (evidence: `src/assistant/audio/capture.py`)
- Assistant Pipeline → Speech Recognition: transcribes audio (evidence: `src/assistant/pipeline.py`)
- Assistant Pipeline → Request Router: routes request (evidence: `src/assistant/pipeline.py`)
- Assistant Pipeline → Local LLM: requests completion (evidence: `src/assistant/pipeline.py`)
- Assistant Pipeline → Remote LLM: requests completion (evidence: `src/assistant/pipeline.py`)
- Assistant Pipeline → Agent Dispatch: dispatches tasks (evidence: `src/assistant/pipeline.py`)
- Assistant Pipeline → Sound Effects: plays effects (evidence: `src/assistant/pipeline.py`)
- Assistant Pipeline → Notifications: sends notifications (evidence: `src/assistant/pipeline.py`)
- Assistant Pipeline → Notch Island UI: updates UI state
- Island Window → Notch Island UI: hosts view (evidence: `src/assistant/ui/island_window.py`)
- User → Notch Island UI: drops files (evidence: `README.md`)
- Assistant Pipeline → Configuration: checks permissions (evidence: `src/assistant/pipeline.py`)
- Local LLM → User: uses local model service (evidence: `src/assistant/llm/local.py`)
- Remote LLM → User: uses provider API (evidence: `README.md`)
