# cmagnussen/blitztext-app architecture

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

- Interactive diagram: https://gitdiagram.com/cmagnussen/blitztext-app
- Repository: https://github.com/cmagnussen/blitztext-app

## Overview

Blitztext is an experimental macOS menu-bar app that captures speech and returns text to the app the user was working in. The principal path is hotkey or menu selection → workflow → microphone recording → online or local transcription → optional rewriting → paste. Separate workflows provide text improvement, calmer-message rewriting, and emoji insertion. AppState coordinates workflow state and paste handling; settings and services support API credentials, local models, permissions, and hotkeys. The README documents both transcription modes and all rewrite variants. Some workflow implementations and wiring were not sampled, so uncertain internal calls are omitted.

Main entry points: [`BlitztextMac/App/AppState.swift`](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/App/AppState.swift) (App State), [`BlitztextMac/Features/Settings/SettingsContentView.swift`](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Settings/SettingsContentView.swift) (Settings UI), [`BlitztextMac/Services/BlitztextCleanupService.swift`](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/BlitztextCleanupService.swift) (User Data Cleanup), [`BlitztextMac/Services/LLMService.swift`](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/LLMService.swift) (Rewrite Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Menu Bar App"]
  node_app["App Lifecycle"]
  node_appstate["App State<br/>[AppState.swift]"]
  node_menubar["Menu Bar UI<br/>[MenuBarView.swift]"]
  node_settingsview["Settings UI"]
  node_hotkey["Hotkey Monitor"]
end

subgraph group_workflow["Workflow Layer"]
  node_protocol["Workflow Types"]
  node_transcriptionflow["Speech Workflows"]
  node_improvement["Text Improvement"]
  node_calmer["Calmer Message"]
  node_emoji["Emoji Text"]
end

subgraph group_services["Speech And AI Services"]
  node_recorder["Audio Recorder"]
  node_remote_transcription["Online Transcription"]
  node_local_transcription["Local Transcription"]
  node_llm["Rewrite Service<br/>[LLMService.swift]"]
  node_quality["Transcription Quality"]
end

subgraph group_settings["Configuration And Access"]
  node_keychain[("API Key Storage")]
  node_supportpaths["App Data Paths"]
  node_accessibility["Accessibility Permission"]
  node_login["Launch At Login"]
  node_cleanup["User Data Cleanup"]
  node_install["Install Location"]
end

node_user(("User"))
node_target_app["Text App"]
node_openai{{"OpenAI API"}}
node_whisperkit{{"WhisperKit / CoreML"}}

node_user -->|"selects workflow"| node_menubar
node_user -->|"presses hotkey"| node_hotkey
node_menubar -->|"starts workflow"| node_appstate
node_hotkey -->|"sends events"| node_appstate
node_app -->|"initializes"| node_appstate
node_appstate -->|"uses workflow types"| node_protocol
node_appstate -->|"starts"| node_transcriptionflow
node_appstate -->|"starts"| node_improvement
node_appstate -->|"starts"| node_calmer
node_appstate -->|"starts"| node_emoji
node_appstate -->|"pastes text"| node_target_app
node_appstate -->|"checks permission"| node_accessibility
node_settingsview -->|"edits settings"| node_appstate
node_transcriptionflow -->|"records audio"| node_recorder
node_transcriptionflow -->|"transcribes online"| node_remote_transcription
node_transcriptionflow -->|"transcribes locally"| node_local_transcription
node_improvement -->|"rewrites text"| node_llm
node_calmer -->|"rewrites text"| node_llm
node_emoji -->|"adds emojis"| node_llm
node_remote_transcription -->|"sends audio"| node_openai
node_llm -->|"sends text"| node_openai
node_local_transcription -->|"runs on device"| node_whisperkit
node_remote_transcription -->|"loads API key"| node_keychain
node_llm -->|"loads API key"| node_keychain
node_local_transcription -->|"uses model path"| node_supportpaths
node_appstate -.->|"checks transcription"| node_quality
node_settingsview -->|"saves API key"| node_keychain
node_settingsview -->|"configures startup"| node_login
node_settingsview -->|"requests cleanup"| node_cleanup
node_settingsview -->|"requests move"| node_install
node_cleanup -->|"deletes API key"| node_keychain
node_cleanup -->|"removes app data"| node_supportpaths
node_cleanup -->|"unregisters startup"| node_login
node_cleanup -->|"lists installations"| node_install

click node_app "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/App/BlitztextMacApp.swift"
click node_appstate "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/App/AppState.swift"
click node_menubar "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/MenuBar/MenuBarView.swift"
click node_settingsview "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Settings/SettingsContentView.swift"
click node_hotkey "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/HotkeyService.swift"
click node_protocol "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/WorkflowProtocol.swift"
click node_transcriptionflow "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/TranscriptionWorkflow.swift"
click node_improvement "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/TextImprovementWorkflow.swift"
click node_calmer "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/DampfAblassenWorkflow.swift"
click node_emoji "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/EmojiTextWorkflow.swift"
click node_recorder "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/AudioRecorder.swift"
click node_remote_transcription "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/TranscriptionService.swift"
click node_local_transcription "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/LocalTranscriptionService.swift"
click node_llm "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/LLMService.swift"
click node_quality "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/TranscriptionQualityService.swift"
click node_keychain "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/KeychainService.swift"
click node_supportpaths "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/AppSupportPaths.swift"
click node_accessibility "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/AccessibilityPermissionService.swift"
click node_login "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/LaunchAtLoginService.swift"
click node_cleanup "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/BlitztextCleanupService.swift"
click node_install "https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/BlitztextInstallLocationService.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_app,node_appstate,node_menubar,node_settingsview,node_hotkey,node_user toneBlue
class node_protocol,node_transcriptionflow,node_improvement,node_calmer,node_emoji toneAmber
class node_recorder,node_remote_transcription,node_local_transcription,node_llm,node_quality,node_openai toneMint
class node_keychain,node_supportpaths,node_accessibility,node_login,node_cleanup,node_install toneRose
class node_target_app,node_whisperkit toneIndigo
```

## Components

### Menu Bar App

- [App Lifecycle](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/App/BlitztextMacApp.swift): `BlitztextMac/App/BlitztextMacApp.swift`
- [App State](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/App/AppState.swift): `BlitztextMac/App/AppState.swift`
- [Menu Bar UI](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/MenuBar/MenuBarView.swift): `BlitztextMac/Features/MenuBar/MenuBarView.swift`
- [Settings UI](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Settings/SettingsContentView.swift): `BlitztextMac/Features/Settings/SettingsContentView.swift`
- [Hotkey Monitor](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/HotkeyService.swift): `BlitztextMac/Services/HotkeyService.swift`

### Workflow Layer

- [Workflow Types](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/WorkflowProtocol.swift): `BlitztextMac/Features/Workflows/WorkflowProtocol.swift`
- [Speech Workflows](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/TranscriptionWorkflow.swift): `BlitztextMac/Features/Workflows/TranscriptionWorkflow.swift`
- [Text Improvement](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/TextImprovementWorkflow.swift): `BlitztextMac/Features/Workflows/TextImprovementWorkflow.swift`
- [Calmer Message](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/DampfAblassenWorkflow.swift): `BlitztextMac/Features/Workflows/DampfAblassenWorkflow.swift`
- [Emoji Text](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Features/Workflows/EmojiTextWorkflow.swift): `BlitztextMac/Features/Workflows/EmojiTextWorkflow.swift`

### Speech And AI Services

- [Audio Recorder](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/AudioRecorder.swift): `BlitztextMac/Services/AudioRecorder.swift`
- [Online Transcription](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/TranscriptionService.swift): `BlitztextMac/Services/TranscriptionService.swift`
- [Local Transcription](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/LocalTranscriptionService.swift): `BlitztextMac/Services/LocalTranscriptionService.swift`
- [Rewrite Service](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/LLMService.swift): `BlitztextMac/Services/LLMService.swift`
- [Transcription Quality](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/TranscriptionQualityService.swift): `BlitztextMac/Services/TranscriptionQualityService.swift`

### Configuration And Access

- [API Key Storage](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/KeychainService.swift): `BlitztextMac/Services/KeychainService.swift`
- [App Data Paths](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/AppSupportPaths.swift): `BlitztextMac/Services/AppSupportPaths.swift`
- [Accessibility Permission](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/AccessibilityPermissionService.swift): `BlitztextMac/Services/AccessibilityPermissionService.swift`
- [Launch At Login](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/LaunchAtLoginService.swift): `BlitztextMac/Services/LaunchAtLoginService.swift`
- [User Data Cleanup](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/BlitztextCleanupService.swift): `BlitztextMac/Services/BlitztextCleanupService.swift`
- [Install Location](https://github.com/cmagnussen/blitztext-app/blob/main/BlitztextMac/Services/BlitztextInstallLocationService.swift): `BlitztextMac/Services/BlitztextInstallLocationService.swift`

### Other components

- **User**
- **Text App**
- **OpenAI API**
- **WhisperKit / CoreML**

## Connections

- User → Menu Bar UI: selects workflow
- User → Hotkey Monitor: presses hotkey
- Menu Bar UI → App State: starts workflow
- Hotkey Monitor → App State: sends events
- App Lifecycle → App State: initializes
- App State → Workflow Types: uses workflow types
- App State → Speech Workflows: starts
- App State → Text Improvement: starts
- App State → Calmer Message: starts
- App State → Emoji Text: starts
- App State → Text App: pastes text
- App State → Accessibility Permission: checks permission
- Settings UI → App State: edits settings
- Speech Workflows → Audio Recorder: records audio
- Speech Workflows → Online Transcription: transcribes online
- Speech Workflows → Local Transcription: transcribes locally
- Text Improvement → Rewrite Service: rewrites text
- Calmer Message → Rewrite Service: rewrites text
- Emoji Text → Rewrite Service: adds emojis
- Online Transcription → OpenAI API: sends audio
- Rewrite Service → OpenAI API: sends text
- Local Transcription → WhisperKit / CoreML: runs on device
- Online Transcription → API Key Storage: loads API key
- Rewrite Service → API Key Storage: loads API key
- Local Transcription → App Data Paths: uses model path
- App State → Transcription Quality: checks transcription
- Settings UI → API Key Storage: saves API key
- Settings UI → Launch At Login: configures startup
- Settings UI → User Data Cleanup: requests cleanup
- Settings UI → Install Location: requests move
- User Data Cleanup → API Key Storage: deletes API key
- User Data Cleanup → App Data Paths: removes app data
- User Data Cleanup → Launch At Login: unregisters startup
- User Data Cleanup → Install Location: lists installations