# fsouza-dot/openwhisper architecture

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

- Interactive diagram: https://gitdiagram.com/fsouza-dot/openwhisper
- Repository: https://github.com/fsouza-dot/openwhisper

## Overview

OpenWhisper is a desktop push-to-talk dictation assistant: a global hotkey starts and ends microphone capture, speech is transcribed locally or through Groq, cleanup interprets formatting commands, and text is inserted into the foreground app. The app composition root wires the coordinator to the hotkey and UI. The sampled coordinator source was not provided, so its internal call wiring is not shown; workflow connections reflect the documented product behavior. Settings, history, and platform insertion are additional product capabilities.

Main entry points: [`openwhisper/app.py`](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/app.py) (App composition), [`openwhisper/coordinator.py`](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/coordinator.py) (Dictation coordinator), [`openwhisper/cleanup/pipeline.py`](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/cleanup/pipeline.py) (Transcript cleanup), [`openwhisper/hotkey/hotkey_manager.py`](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/hotkey/hotkey_manager.py) (Global hotkey)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Dictation capture"]
  node_hotkey["Global hotkey<br/>[hotkey_manager.py]"]
  node_recorder["Audio recorder<br/>[recorder.py]"]
  node_coordinator["Dictation coordinator<br/>[coordinator.py]"]
end

subgraph group_speech["Speech and cleanup"]
  node_whisper["Local Whisper"]
  node_groq["Groq transcription<br/>[groq_provider.py]"]
  node_cleanup["Transcript cleanup<br/>[pipeline.py]"]
  node_heuristics["Text heuristics<br/>[heuristic.py]"]
  node_commands["Voice commands<br/>[interpreter.py]"]
  node_dictionary["Custom dictionary<br/>[dictionary.py]"]
end

subgraph group_delivery["Text delivery"]
  node_inserter["Text insertion<br/>[base_inserter.py]"]
  node_platform["Platform adapters"]
end

subgraph group_app["Desktop app"]
  node_app["App composition<br/>[app.py]"]
  node_tray["Tray and HUD<br/>[tray.py]"]
  node_settings_ui["Settings window<br/>[settings_window.py]"]
  node_settings["App settings<br/>[settings.py]"]
  node_secrets[("Credential store<br/>[keyring_store.py]")]
  node_history[("Dictation history<br/>[history.py]")]
  node_history_ui["History window<br/>[history_window.py]"]
  node_usage[("Usage tracking<br/>[usage.py]")]
end

node_user(("User"))
node_microphone(("Microphone"))
node_groq_service(("Groq API"))
node_foreground(("Active application"))

node_user -->|"presses and releases"| node_hotkey
node_hotkey -->|"dispatches events"| node_coordinator
node_coordinator -->|"controls capture"| node_recorder
node_microphone -->|"provides audio"| node_recorder
node_coordinator -->|"transcribes locally"| node_whisper
node_coordinator -.->|"requests transcription"| node_groq
node_groq -.->|"sends audio"| node_groq_service
node_coordinator -->|"cleans transcript"| node_cleanup
node_cleanup -->|"applies cleanup"| node_heuristics
node_cleanup -->|"interprets phrases"| node_commands
node_whisper -->|"uses vocabulary hints"| node_dictionary
node_coordinator -->|"inserts result"| node_inserter
node_inserter -->|"uses adapter"| node_platform
node_platform -->|"pastes text"| node_foreground
node_app -->|"wires service"| node_coordinator
node_app -->|"wires hotkey"| node_hotkey
node_app -->|"connects UI"| node_tray
node_app -->|"connects settings"| node_settings_ui
node_settings_ui -->|"edits configuration"| node_settings
node_app -->|"loads settings"| node_settings
node_app -->|"stores credentials"| node_secrets
node_app -->|"owns history"| node_history
node_history_ui -->|"reads entries"| node_history
node_app -->|"tracks usage"| node_usage

click node_hotkey "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/hotkey/hotkey_manager.py"
click node_recorder "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/audio/recorder.py"
click node_coordinator "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/coordinator.py"
click node_whisper "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/stt/whisper_provider.py"
click node_groq "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/stt/groq_provider.py"
click node_cleanup "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/cleanup/pipeline.py"
click node_heuristics "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/cleanup/heuristic.py"
click node_commands "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/commands/interpreter.py"
click node_dictionary "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/cleanup/dictionary.py"
click node_inserter "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/platform/base_inserter.py"
click node_platform "https://github.com/fsouza-dot/openwhisper/tree/main/openwhisper/platform"
click node_app "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/app.py"
click node_tray "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/ui/tray.py"
click node_settings_ui "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/ui/settings_window.py"
click node_settings "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/settings.py"
click node_secrets "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/keyring_store.py"
click node_history "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/history.py"
click node_history_ui "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/ui/history_window.py"
click node_usage "https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/usage.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_hotkey,node_recorder,node_coordinator,node_user toneBlue
class node_whisper,node_groq,node_cleanup,node_heuristics,node_commands,node_dictionary toneAmber
class node_inserter,node_platform,node_groq_service toneMint
class node_app,node_tray,node_settings_ui,node_settings,node_secrets,node_history,node_history_ui,node_usage toneRose
class node_microphone,node_foreground toneIndigo
```

## Components

### Dictation capture

- [Global hotkey](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/hotkey/hotkey_manager.py): `openwhisper/hotkey/hotkey_manager.py`
- [Audio recorder](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/audio/recorder.py): `openwhisper/audio/recorder.py`
- [Dictation coordinator](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/coordinator.py): `openwhisper/coordinator.py`

### Speech and cleanup

- [Local Whisper](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/stt/whisper_provider.py): `openwhisper/stt/whisper_provider.py`
- [Groq transcription](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/stt/groq_provider.py): `openwhisper/stt/groq_provider.py`
- [Transcript cleanup](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/cleanup/pipeline.py): `openwhisper/cleanup/pipeline.py`
- [Text heuristics](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/cleanup/heuristic.py): `openwhisper/cleanup/heuristic.py`
- [Voice commands](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/commands/interpreter.py): `openwhisper/commands/interpreter.py`
- [Custom dictionary](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/cleanup/dictionary.py): `openwhisper/cleanup/dictionary.py`

### Text delivery

- [Text insertion](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/platform/base_inserter.py): `openwhisper/platform/base_inserter.py`
- [Platform adapters](https://github.com/fsouza-dot/openwhisper/tree/main/openwhisper/platform): `openwhisper/platform`

### Desktop app

- [App composition](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/app.py): `openwhisper/app.py`
- [Tray and HUD](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/ui/tray.py): `openwhisper/ui/tray.py`
- [Settings window](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/ui/settings_window.py): `openwhisper/ui/settings_window.py`
- [App settings](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/settings.py): `openwhisper/settings.py`
- [Credential store](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/keyring_store.py): `openwhisper/keyring_store.py`
- [Dictation history](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/history.py): `openwhisper/history.py`
- [History window](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/ui/history_window.py): `openwhisper/ui/history_window.py`
- [Usage tracking](https://github.com/fsouza-dot/openwhisper/blob/main/openwhisper/usage.py): `openwhisper/usage.py`

### Other components

- **User**
- **Microphone**
- **Groq API**
- **Active application**

## Connections

- User → Global hotkey: presses and releases
- Global hotkey → Dictation coordinator: dispatches events
- Dictation coordinator → Audio recorder: controls capture
- Microphone → Audio recorder: provides audio
- Dictation coordinator → Local Whisper: transcribes locally
- Dictation coordinator → Groq transcription: requests transcription
- Groq transcription → Groq API: sends audio
- Dictation coordinator → Transcript cleanup: cleans transcript
- Transcript cleanup → Text heuristics: applies cleanup
- Transcript cleanup → Voice commands: interprets phrases
- Local Whisper → Custom dictionary: uses vocabulary hints
- Dictation coordinator → Text insertion: inserts result
- Text insertion → Platform adapters: uses adapter
- Platform adapters → Active application: pastes text
- App composition → Dictation coordinator: wires service
- App composition → Global hotkey: wires hotkey
- App composition → Tray and HUD: connects UI
- App composition → Settings window: connects settings
- Settings window → App settings: edits configuration
- App composition → App settings: loads settings
- App composition → Credential store: stores credentials
- App composition → Dictation history: owns history
- History window → Dictation history: reads entries
- App composition → Usage tracking: tracks usage