# sho-luv/voice architecture

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

- Interactive diagram: https://gitdiagram.com/sho-luv/voice
- Repository: https://github.com/sho-luv/voice

## Overview

Voice is a local macOS dictation app: the user triggers recording, speech is transcribed and optionally cleaned up, then text is inserted into the active app. The README also documents model management, settings, transcription history, and the floating status overlay. The supplied excerpts show the input monitor, cleanup logic, model-loading wrapper, and native engine; several app responsibilities are documented but their detailed wiring is not visible, so the graph omits uncertain links.

Main entry points: [`Voice.swift`](https://github.com/sho-luv/voice/blob/main/Voice.swift) (App controller), [`SpeechEngine.swift`](https://github.com/sho-luv/voice/blob/main/SpeechEngine.swift) (Speech engine wrapper), [`engine/VoiceEngine.cpp`](https://github.com/sho-luv/voice/blob/main/engine/VoiceEngine.cpp) (Native ASR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Dictation interaction"]
  node_input_monitor["Hotkey monitor<br/>[Voice.swift]"]
  node_audio_capture["Audio capture<br/>[Voice.swift]"]
  node_app_controller["App controller<br/>[Voice.swift]"]
  node_overlay["Status overlay<br/>[Voice.swift]"]
  node_text_insertion["Text insertion<br/>[Voice.swift]"]
end

subgraph group_transcription["Transcription and cleanup"]
  node_speech_engine["Speech engine wrapper<br/>[SpeechEngine.swift]"]
  node_asr_native["Native ASR<br/>[VoiceEngine.cpp]"]
  node_speech_models["Whisper / Parakeet<br/>[VoiceEngine.cpp]"]
  node_text_cleanup["Transcript cleanup<br/>[Voice.swift]"]
  node_llm_native["Native cleanup LLM<br/>[VoiceEngine.cpp]"]
end

subgraph group_models["Model management"]
  node_model_catalog["Model catalog<br/>[SpeechEngine.swift]"]
  node_model_downloader["Model downloader<br/>[Voice.swift]"]
  node_model_store[("Local model files<br/>[SpeechEngine.swift]")]
end

subgraph group_app_features["App features and storage"]
  node_settings["Settings<br/>[Voice.swift]"]
  node_user_defaults[("UserDefaults")]
  node_transcript_history["Transcript history<br/>[Voice.swift]"]
  node_transcript_files[("Transcript files<br/>[Voice.swift]")]
end

node_user(("User"))
node_active_app["Active app"]
node_hugging_face["Hugging Face"]

node_user -->|"presses hotkey"| node_input_monitor
node_input_monitor -->|"signals recording"| node_app_controller
node_app_controller -->|"starts / stops"| node_audio_capture
node_app_controller -->|"prepares and transcribes"| node_speech_engine
node_audio_capture -->|"provides audio"| node_speech_engine
node_speech_engine -->|"calls native API"| node_asr_native
node_asr_native -->|"runs inference"| node_speech_models
node_app_controller -->|"requests cleanup"| node_text_cleanup
node_text_cleanup -->|"requests LLM rewrite"| node_speech_engine
node_speech_engine -->|"calls native API"| node_llm_native
node_app_controller -->|"inserts transcript"| node_text_insertion
node_text_insertion -->|"injects or pastes"| node_active_app
node_app_controller -->|"updates status"| node_overlay
node_user -->|"requests download"| node_model_downloader
node_model_downloader -->|"downloads models"| node_hugging_face
node_model_downloader -->|"saves models"| node_model_store
node_model_catalog -->|"locates and verifies"| node_model_store
node_settings -->|"persists preferences"| node_user_defaults
node_user -->|"configures app"| node_settings
node_app_controller -->|"saves finished transcript"| node_transcript_history
node_transcript_history -->|"writes and searches"| node_transcript_files
node_user -->|"browses history"| node_transcript_history

click node_input_monitor "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_audio_capture "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_app_controller "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_overlay "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_text_insertion "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_speech_engine "https://github.com/sho-luv/voice/blob/main/SpeechEngine.swift"
click node_asr_native "https://github.com/sho-luv/voice/blob/main/engine/VoiceEngine.cpp"
click node_speech_models "https://github.com/sho-luv/voice/blob/main/engine/VoiceEngine.cpp"
click node_text_cleanup "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_llm_native "https://github.com/sho-luv/voice/blob/main/engine/VoiceEngine.cpp"
click node_model_catalog "https://github.com/sho-luv/voice/blob/main/SpeechEngine.swift"
click node_model_downloader "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_model_store "https://github.com/sho-luv/voice/blob/main/SpeechEngine.swift"
click node_settings "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_transcript_history "https://github.com/sho-luv/voice/blob/main/Voice.swift"
click node_transcript_files "https://github.com/sho-luv/voice/blob/main/Voice.swift"

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_input_monitor,node_audio_capture,node_app_controller,node_overlay,node_text_insertion,node_user toneBlue
class node_speech_engine,node_asr_native,node_speech_models,node_text_cleanup,node_llm_native toneAmber
class node_model_catalog,node_model_downloader,node_model_store toneMint
class node_settings,node_user_defaults,node_transcript_history,node_transcript_files toneRose
class node_active_app,node_hugging_face toneIndigo
```

## Components

### Dictation interaction

- [Hotkey monitor](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`
- [Audio capture](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`
- [App controller](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`
- [Status overlay](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`
- [Text insertion](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`

### Transcription and cleanup

- [Speech engine wrapper](https://github.com/sho-luv/voice/blob/main/SpeechEngine.swift): `SpeechEngine.swift`
- [Native ASR](https://github.com/sho-luv/voice/blob/main/engine/VoiceEngine.cpp): `engine/VoiceEngine.cpp`
- [Whisper / Parakeet](https://github.com/sho-luv/voice/blob/main/engine/VoiceEngine.cpp): `engine/VoiceEngine.cpp`
- [Transcript cleanup](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`
- [Native cleanup LLM](https://github.com/sho-luv/voice/blob/main/engine/VoiceEngine.cpp): `engine/VoiceEngine.cpp`

### Model management

- [Model catalog](https://github.com/sho-luv/voice/blob/main/SpeechEngine.swift): `SpeechEngine.swift`
- [Model downloader](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`
- [Local model files](https://github.com/sho-luv/voice/blob/main/SpeechEngine.swift): `SpeechEngine.swift`

### App features and storage

- [Settings](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`
- **UserDefaults**
- [Transcript history](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`
- [Transcript files](https://github.com/sho-luv/voice/blob/main/Voice.swift): `Voice.swift`

### Other components

- **User**
- **Active app**
- **Hugging Face**

## Connections

- User → Hotkey monitor: presses hotkey
- Hotkey monitor → App controller: signals recording
- App controller → Audio capture: starts / stops
- App controller → Speech engine wrapper: prepares and transcribes
- Audio capture → Speech engine wrapper: provides audio
- Speech engine wrapper → Native ASR: calls native API
- Native ASR → Whisper / Parakeet: runs inference
- App controller → Transcript cleanup: requests cleanup
- Transcript cleanup → Speech engine wrapper: requests LLM rewrite
- Speech engine wrapper → Native cleanup LLM: calls native API
- App controller → Text insertion: inserts transcript
- Text insertion → Active app: injects or pastes
- App controller → Status overlay: updates status
- User → Model downloader: requests download
- Model downloader → Hugging Face: downloads models
- Model downloader → Local model files: saves models
- Model catalog → Local model files: locates and verifies
- Settings → UserDefaults: persists preferences
- User → Settings: configures app
- App controller → Transcript history: saves finished transcript
- Transcript history → Transcript files: writes and searches
- User → Transcript history: browses history