# cjpais/handy architecture

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

- Interactive diagram: https://gitdiagram.com/cjpais/handy
- Repository: https://github.com/cjpais/handy

## Overview

Handy is a cross-platform desktop speech-to-text app designed to transcribe speech locally and paste the result into the active application. Its primary workflow is shortcut activation, audio capture, speech processing, then text insertion; settings, model management, history, onboarding, and optional post-processing support that flow. The README documents the user-facing capabilities; source excerpts and the index substantiate selected internal connections, while unsampled subsystem links are omitted or marked unverified.

Main entry points: [`src-tauri/src/actions.rs`](https://github.com/cjpais/handy/blob/main/src-tauri/src/actions.rs) (Transcription actions), [`src/App.tsx`](https://github.com/cjpais/handy/blob/main/src/App.tsx) (App shell), [`src/components/settings/index.ts`](https://github.com/cjpais/handy/blob/main/src/components/settings/index.ts) (Settings interface), [`src-tauri/src/shortcut/handler.rs`](https://github.com/cjpais/handy/blob/main/src-tauri/src/shortcut/handler.rs) (Shortcut handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Desktop interface"]
  node_app["App shell<br/>[App.tsx]"]
  node_onboarding["Onboarding<br/>[OnboardingFlow.tsx]"]
  node_overlay["Recording overlay"]
  node_settings_ui["Settings interface<br/>[index.ts]"]
end

subgraph group_capture["Recording and input"]
  node_shortcut["Shortcut handler<br/>[handler.rs]"]
  node_actions["Transcription actions<br/>[actions.rs]"]
  node_audio["Audio recording<br/>[audio.rs]"]
  node_paste["Text insertion<br/>[clipboard.rs]"]
end

subgraph group_speech["Speech processing"]
  node_coordinator["Transcription coordinator"]
  node_transcription["Transcription engine<br/>[transcription.rs]"]
  node_vad["Voice activity detection"]
  node_models["Model management<br/>[model.rs]"]
  node_catalog["Model catalog<br/>[mod.rs]"]
end

subgraph group_state["Settings and history"]
  node_settings_store["Settings state<br/>[settingsStore.ts]"]
  node_settings_backend[("Settings persistence<br/>[settings.rs]")]
  node_history[("Transcript history<br/>[history.rs]")]
end

subgraph group_extensions["Optional capabilities"]
  node_postprocess["LLM post-processing<br/>[llm_client.rs]"]
  node_hook["Transcription hook"]
  node_cli["CLI controls<br/>[cli.rs]"]
end

node_user(("User"))
node_external_app["Active application"]
node_llm_provider["LLM provider"]

node_user -->|"activates"| node_shortcut
node_shortcut -->|"dispatches"| node_actions
node_actions -->|"starts recording"| node_audio
node_actions -->|"coordinates"| node_coordinator
node_actions -->|"transcribes"| node_transcription
node_actions -->|"uses VAD"| node_vad
node_actions -->|"selects model"| node_models
node_actions -->|"saves transcript"| node_history
node_actions -.->|"inserts text"| node_paste
node_paste -->|"pastes into"| node_external_app
node_user -.->|"configures"| node_app
node_app -->|"presents"| node_onboarding
node_app -->|"shows settings"| node_settings_ui
node_settings_ui -.->|"updates"| node_settings_store
node_settings_store -.->|"reads and writes"| node_settings_backend
node_user -.->|"views status"| node_overlay
node_models -.->|"uses catalog"| node_catalog
node_actions -.->|"post-processes text"| node_postprocess
node_postprocess -->|"sends request"| node_llm_provider
node_actions -.->|"rewrites text"| node_hook
node_user -.->|"controls app"| node_cli

click node_app "https://github.com/cjpais/handy/blob/main/src/App.tsx"
click node_onboarding "https://github.com/cjpais/handy/blob/main/src/components/onboarding/OnboardingFlow.tsx"
click node_overlay "https://github.com/cjpais/handy/blob/main/src/overlay/RecordingOverlay.tsx"
click node_shortcut "https://github.com/cjpais/handy/blob/main/src-tauri/src/shortcut/handler.rs"
click node_actions "https://github.com/cjpais/handy/blob/main/src-tauri/src/actions.rs"
click node_audio "https://github.com/cjpais/handy/blob/main/src-tauri/src/managers/audio.rs"
click node_coordinator "https://github.com/cjpais/handy/blob/main/src-tauri/src/transcription_coordinator.rs"
click node_transcription "https://github.com/cjpais/handy/blob/main/src-tauri/src/managers/transcription.rs"
click node_vad "https://github.com/cjpais/handy/tree/main/src-tauri/src/audio_toolkit/vad"
click node_models "https://github.com/cjpais/handy/blob/main/src-tauri/src/managers/model.rs"
click node_paste "https://github.com/cjpais/handy/blob/main/src-tauri/src/clipboard.rs"
click node_settings_ui "https://github.com/cjpais/handy/blob/main/src/components/settings/index.ts"
click node_settings_store "https://github.com/cjpais/handy/blob/main/src/stores/settingsStore.ts"
click node_settings_backend "https://github.com/cjpais/handy/blob/main/src-tauri/src/settings.rs"
click node_history "https://github.com/cjpais/handy/blob/main/src-tauri/src/managers/history.rs"
click node_catalog "https://github.com/cjpais/handy/blob/main/src-tauri/src/catalog/mod.rs"
click node_postprocess "https://github.com/cjpais/handy/blob/main/src-tauri/src/llm_client.rs"
click node_hook "https://github.com/cjpais/handy/blob/main/src-tauri/src/transcription_hook.rs"
click node_cli "https://github.com/cjpais/handy/blob/main/src-tauri/src/cli.rs"

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_onboarding,node_overlay,node_settings_ui,node_user toneBlue
class node_shortcut,node_actions,node_audio,node_paste toneAmber
class node_coordinator,node_transcription,node_vad,node_models,node_catalog toneMint
class node_settings_store,node_settings_backend,node_history toneRose
class node_postprocess,node_hook,node_cli,node_external_app,node_llm_provider toneIndigo
```

## Components

### Desktop interface

- [App shell](https://github.com/cjpais/handy/blob/main/src/App.tsx): `src/App.tsx`
- [Onboarding](https://github.com/cjpais/handy/blob/main/src/components/onboarding/OnboardingFlow.tsx): `src/components/onboarding/OnboardingFlow.tsx`
- [Recording overlay](https://github.com/cjpais/handy/blob/main/src/overlay/RecordingOverlay.tsx): `src/overlay/RecordingOverlay.tsx`
- [Settings interface](https://github.com/cjpais/handy/blob/main/src/components/settings/index.ts): `src/components/settings/index.ts`

### Recording and input

- [Shortcut handler](https://github.com/cjpais/handy/blob/main/src-tauri/src/shortcut/handler.rs): `src-tauri/src/shortcut/handler.rs`
- [Transcription actions](https://github.com/cjpais/handy/blob/main/src-tauri/src/actions.rs): `src-tauri/src/actions.rs`
- [Audio recording](https://github.com/cjpais/handy/blob/main/src-tauri/src/managers/audio.rs): `src-tauri/src/managers/audio.rs`
- [Text insertion](https://github.com/cjpais/handy/blob/main/src-tauri/src/clipboard.rs): `src-tauri/src/clipboard.rs`

### Speech processing

- [Transcription coordinator](https://github.com/cjpais/handy/blob/main/src-tauri/src/transcription_coordinator.rs): `src-tauri/src/transcription_coordinator.rs`
- [Transcription engine](https://github.com/cjpais/handy/blob/main/src-tauri/src/managers/transcription.rs): `src-tauri/src/managers/transcription.rs`
- [Voice activity detection](https://github.com/cjpais/handy/tree/main/src-tauri/src/audio_toolkit/vad): `src-tauri/src/audio_toolkit/vad`
- [Model management](https://github.com/cjpais/handy/blob/main/src-tauri/src/managers/model.rs): `src-tauri/src/managers/model.rs`
- [Model catalog](https://github.com/cjpais/handy/blob/main/src-tauri/src/catalog/mod.rs): `src-tauri/src/catalog/mod.rs`

### Settings and history

- [Settings state](https://github.com/cjpais/handy/blob/main/src/stores/settingsStore.ts): `src/stores/settingsStore.ts`
- [Settings persistence](https://github.com/cjpais/handy/blob/main/src-tauri/src/settings.rs): `src-tauri/src/settings.rs`
- [Transcript history](https://github.com/cjpais/handy/blob/main/src-tauri/src/managers/history.rs): `src-tauri/src/managers/history.rs`

### Optional capabilities

- [LLM post-processing](https://github.com/cjpais/handy/blob/main/src-tauri/src/llm_client.rs): `src-tauri/src/llm_client.rs`
- [Transcription hook](https://github.com/cjpais/handy/blob/main/src-tauri/src/transcription_hook.rs): `src-tauri/src/transcription_hook.rs`
- [CLI controls](https://github.com/cjpais/handy/blob/main/src-tauri/src/cli.rs): `src-tauri/src/cli.rs`

### Other components

- **User**
- **Active application**
- **LLM provider**

## Connections

- User → Shortcut handler: activates (evidence: `README.md`)
- Shortcut handler → Transcription actions: dispatches (evidence: `src-tauri/src/shortcut/handler.rs`)
- Transcription actions → Audio recording: starts recording (evidence: `src-tauri/src/actions.rs`)
- Transcription actions → Transcription coordinator: coordinates (evidence: `src-tauri/src/transcription_coordinator.rs`)
- Transcription actions → Transcription engine: transcribes (evidence: `src-tauri/src/actions.rs`)
- Transcription actions → Voice activity detection: uses VAD (evidence: `src-tauri/src/actions.rs`)
- Transcription actions → Model management: selects model (evidence: `src-tauri/src/actions.rs`)
- Transcription actions → Transcript history: saves transcript (evidence: `src-tauri/src/actions.rs`)
- Transcription actions → Text insertion: inserts text (evidence: `README.md`)
- Text insertion → Active application: pastes into (evidence: `README.md`)
- User → App shell: configures
- App shell → Onboarding: presents (evidence: `src/App.tsx`)
- App shell → Settings interface: shows settings (evidence: `src/App.tsx`)
- Settings interface → Settings state: updates
- Settings state → Settings persistence: reads and writes
- User → Recording overlay: views status
- Model management → Model catalog: uses catalog
- Transcription actions → LLM post-processing: post-processes text (evidence: `src-tauri/src/actions.rs`)
- LLM post-processing → LLM provider: sends request (evidence: `src-tauri/src/llm_client.rs`)
- Transcription actions → Transcription hook: rewrites text (evidence: `README.md`)
- User → CLI controls: controls app (evidence: `README.md`)
