# vishwaksen21/avelyn architecture

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

- Interactive diagram: https://gitdiagram.com/vishwaksen21/avelyn
- Repository: https://github.com/vishwaksen21/avelyn

## Overview

Avelyn is a cross-platform desktop text-enhancement app: users select text in another application, trigger a global shortcut, preview an AI rewrite, and choose whether to replace the selection. The runtime also supports multiple enhancement modes and providers, onboarding and permissions, local history/productivity features, and voice commands. The README documents the main capture-and-replace flow; sampled excerpts confirm startup, platform clipboard/focus handling, AI-provider responsibilities, and voice components. Some subsystem connections are omitted where their callers were not sampled.

Main entry points: [`main.py`](https://github.com/vishwaksen21/avelyn/blob/main/main.py) (App coordinator), [`providers.py`](https://github.com/vishwaksen21/avelyn/blob/main/providers.py) (Provider adapters), [`platform_handler.py`](https://github.com/vishwaksen21/avelyn/blob/main/platform_handler.py) (Platform input), [`ai_processor.py`](https://github.com/vishwaksen21/avelyn/blob/main/ai_processor.py) (Enhancement processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workflow"]
  node_main["App coordinator<br/>[main.py]"]
  node_hotkeys["Global shortcuts<br/>[hotkeys.py]"]
  node_platform["Platform input"]
  node_clipboard["Clipboard manager"]
  node_ui["Popup and tray UI<br/>[ui.py]"]
end

subgraph group_ai["AI enhancement"]
  node_processor["Enhancement processor<br/>[ai_processor.py]"]
  node_providers["Provider adapters<br/>[providers.py]"]
end

subgraph group_support["Setup and state"]
  node_settings[("Settings<br/>[settings.py]")]
  node_knowledge[("Prompt history<br/>[knowledge_base.py]")]
  node_productivity["Usage tracking<br/>[productivity.py]"]
  node_permissions["Permission checks<br/>[permissions.py]"]
  node_onboarding["Setup wizard<br/>[onboarding.py]"]
  node_installer["Ollama setup<br/>[installer.py]"]
end

subgraph group_voice["Voice commands"]
  node_voice_handler["Voice command handler<br/>[voice_handler.py]"]
  node_voice_engine["Audio and transcription<br/>[voice_engine.py]"]
end

subgraph group_web["Product website"]
  node_website_pages["Product and help pages"]
  node_website_components["Site components"]
  node_faq_data["FAQ content<br/>[faqDatabase.ts]"]
  node_docs_data["Docs navigation<br/>[docsNavigation.ts]"]
end

node_user(("User"))
node_target_app["Editing app"]
node_cloud_ai{{"Gemini / OpenAI"}}
node_ollama{{"Ollama service"}}

node_user -->|"selects text"| node_target_app
node_user -->|"presses shortcut"| node_hotkeys
node_hotkeys -->|"dispatches shortcut"| node_main
node_main -->|"captures selection"| node_platform
node_platform -->|"simulates copy"| node_target_app
node_main -->|"reads selection"| node_clipboard
node_clipboard -->|"reads copied text"| node_target_app
node_main -->|"opens preview"| node_ui
node_main -->|"requests enhancement"| node_processor
node_processor -->|"selects backend"| node_providers
node_providers -.->|"sends request"| node_cloud_ai
node_providers -.->|"sends request"| node_ollama
node_providers -->|"streams response"| node_processor
node_ui -->|"confirms replacement"| node_main
node_main -->|"sets enhanced text"| node_clipboard
node_main -->|"pastes text"| node_platform
node_platform -->|"restores focus and pastes"| node_target_app
node_main -->|"loads configuration"| node_settings
node_main -->|"checks access"| node_permissions
node_main -->|"starts setup"| node_onboarding
node_main -.->|"starts Ollama"| node_installer
node_main -->|"initializes voice"| node_voice_handler
node_voice_handler -->|"starts capture"| node_voice_engine
node_voice_handler -->|"requests voice action"| node_processor
node_website_pages -->|"renders with"| node_website_components
node_website_components -->|"searches FAQs"| node_faq_data
node_website_components -->|"lists documentation"| node_docs_data

click node_main "https://github.com/vishwaksen21/avelyn/blob/main/main.py"
click node_hotkeys "https://github.com/vishwaksen21/avelyn/blob/main/hotkeys.py"
click node_platform "https://github.com/vishwaksen21/avelyn/blob/main/platform_handler.py"
click node_clipboard "https://github.com/vishwaksen21/avelyn/blob/main/clipboard_manager.py"
click node_ui "https://github.com/vishwaksen21/avelyn/blob/main/ui.py"
click node_processor "https://github.com/vishwaksen21/avelyn/blob/main/ai_processor.py"
click node_providers "https://github.com/vishwaksen21/avelyn/blob/main/providers.py"
click node_settings "https://github.com/vishwaksen21/avelyn/blob/main/settings.py"
click node_knowledge "https://github.com/vishwaksen21/avelyn/blob/main/knowledge_base.py"
click node_productivity "https://github.com/vishwaksen21/avelyn/blob/main/productivity.py"
click node_permissions "https://github.com/vishwaksen21/avelyn/blob/main/permissions.py"
click node_onboarding "https://github.com/vishwaksen21/avelyn/blob/main/onboarding.py"
click node_installer "https://github.com/vishwaksen21/avelyn/blob/main/installer.py"
click node_voice_handler "https://github.com/vishwaksen21/avelyn/blob/main/voice_handler.py"
click node_voice_engine "https://github.com/vishwaksen21/avelyn/blob/main/voice_engine.py"
click node_website_pages "https://github.com/vishwaksen21/avelyn/tree/main/website/src/app"
click node_website_components "https://github.com/vishwaksen21/avelyn/tree/main/website/src/components"
click node_faq_data "https://github.com/vishwaksen21/avelyn/blob/main/website/src/data/faqDatabase.ts"
click node_docs_data "https://github.com/vishwaksen21/avelyn/blob/main/website/src/data/docsNavigation.ts"

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_hotkeys,node_platform,node_clipboard,node_ui,node_user toneBlue
class node_processor,node_providers toneAmber
class node_settings,node_knowledge,node_productivity,node_permissions,node_onboarding,node_installer toneMint
class node_voice_handler,node_voice_engine toneRose
class node_website_pages,node_website_components,node_faq_data,node_docs_data,node_target_app,node_cloud_ai,node_ollama toneIndigo
```

## Components

### Desktop workflow

- [App coordinator](https://github.com/vishwaksen21/avelyn/blob/main/main.py): `main.py`
- [Global shortcuts](https://github.com/vishwaksen21/avelyn/blob/main/hotkeys.py): `hotkeys.py`
- [Platform input](https://github.com/vishwaksen21/avelyn/blob/main/platform_handler.py): `platform_handler.py`
- [Clipboard manager](https://github.com/vishwaksen21/avelyn/blob/main/clipboard_manager.py): `clipboard_manager.py`
- [Popup and tray UI](https://github.com/vishwaksen21/avelyn/blob/main/ui.py): `ui.py`

### AI enhancement

- [Enhancement processor](https://github.com/vishwaksen21/avelyn/blob/main/ai_processor.py): `ai_processor.py`
- [Provider adapters](https://github.com/vishwaksen21/avelyn/blob/main/providers.py): `providers.py`

### Setup and state

- [Settings](https://github.com/vishwaksen21/avelyn/blob/main/settings.py): `settings.py`
- [Prompt history](https://github.com/vishwaksen21/avelyn/blob/main/knowledge_base.py): `knowledge_base.py`
- [Usage tracking](https://github.com/vishwaksen21/avelyn/blob/main/productivity.py): `productivity.py`
- [Permission checks](https://github.com/vishwaksen21/avelyn/blob/main/permissions.py): `permissions.py`
- [Setup wizard](https://github.com/vishwaksen21/avelyn/blob/main/onboarding.py): `onboarding.py`
- [Ollama setup](https://github.com/vishwaksen21/avelyn/blob/main/installer.py): `installer.py`

### Voice commands

- [Voice command handler](https://github.com/vishwaksen21/avelyn/blob/main/voice_handler.py): `voice_handler.py`
- [Audio and transcription](https://github.com/vishwaksen21/avelyn/blob/main/voice_engine.py): `voice_engine.py`

### Product website

- [Product and help pages](https://github.com/vishwaksen21/avelyn/tree/main/website/src/app): `website/src/app`
- [Site components](https://github.com/vishwaksen21/avelyn/tree/main/website/src/components): `website/src/components`
- [FAQ content](https://github.com/vishwaksen21/avelyn/blob/main/website/src/data/faqDatabase.ts): `website/src/data/faqDatabase.ts`
- [Docs navigation](https://github.com/vishwaksen21/avelyn/blob/main/website/src/data/docsNavigation.ts): `website/src/data/docsNavigation.ts`

### Other components

- **User**
- **Editing app**
- **Gemini / OpenAI**
- **Ollama service**

## Connections

- User → Editing app: selects text
- User → Global shortcuts: presses shortcut
- Global shortcuts → App coordinator: dispatches shortcut
- App coordinator → Platform input: captures selection
- Platform input → Editing app: simulates copy
- App coordinator → Clipboard manager: reads selection
- Clipboard manager → Editing app: reads copied text
- App coordinator → Popup and tray UI: opens preview
- App coordinator → Enhancement processor: requests enhancement
- Enhancement processor → Provider adapters: selects backend
- Provider adapters → Gemini / OpenAI: sends request
- Provider adapters → Ollama service: sends request
- Provider adapters → Enhancement processor: streams response
- Popup and tray UI → App coordinator: confirms replacement
- App coordinator → Clipboard manager: sets enhanced text
- App coordinator → Platform input: pastes text
- Platform input → Editing app: restores focus and pastes
- App coordinator → Settings: loads configuration
- App coordinator → Permission checks: checks access
- App coordinator → Setup wizard: starts setup
- App coordinator → Ollama setup: starts Ollama
- App coordinator → Voice command handler: initializes voice
- Voice command handler → Audio and transcription: starts capture
- Voice command handler → Enhancement processor: requests voice action
- Product and help pages → Site components: renders with
- Site components → FAQ content: searches FAQs
- Site components → Docs navigation: lists documentation
