# kitlangton/hex architecture

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

- Interactive diagram: https://gitdiagram.com/kitlangton/hex
- Repository: https://github.com/kitlangton/hex

## Overview

Hex is a legacy macOS voice-dictation app: users trigger recording with a global hotkey, speak, and have the transcription pasted into the active application. Its runtime also includes model selection and downloads, permissions, settings, transcript history, and word remappings. The sampled code shows recording and transcript persistence calls; the README documents the end-to-end workflow and supported transcription engines. Several substantial modules are indexed but unsampled, so uncertain internal links are omitted.

Main entry points: [`Hex/Features/Transcription/TranscriptionFeature.swift`](https://github.com/kitlangton/hex/blob/main/Hex/Features/Transcription/TranscriptionFeature.swift) (Transcription flow), [`Hex/Features/Settings/SettingsFeature.swift`](https://github.com/kitlangton/hex/blob/main/Hex/Features/Settings/SettingsFeature.swift) (Settings feature), [`Hex/Clients/TranscriptionClient.swift`](https://github.com/kitlangton/hex/blob/main/Hex/Clients/TranscriptionClient.swift) (Transcription engines), [`Hex/Clients/KeyEventMonitorClient.swift`](https://github.com/kitlangton/hex/blob/main/Hex/Clients/KeyEventMonitorClient.swift) (Global key monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App workflow"]
  node_app["App lifecycle"]
  node_appfeature["App feature<br/>[AppFeature.swift]"]
  node_transcription["Transcription flow"]
  node_indicator["Recording indicator"]
end

subgraph group_audio["Capture and transcription"]
  node_keymonitor["Global key monitor"]
  node_hotkeylogic["Hotkey processor"]
  node_recording["Recording client"]
  node_capture["Fast audio capture"]
  node_transcriptionclient["Transcription engines"]
  node_parakeet["Parakeet engine"]
  node_clip["Audio clip preparation"]
  node_pasteboard["Paste and clipboard"]
end

subgraph group_configuration["Settings and models"]
  node_settings["Settings feature"]
  node_settingsmodel["Settings state<br/>[HexSettings.swift]"]
  node_modeldownload["Model downloads"]
  node_modelmatcher["Model matching"]
end

subgraph group_support["Permissions and history"]
  node_permissions["Permission client"]
  node_history["History feature"]
  node_transcriptdata["Transcript records"]
  node_persistence["Transcript persistence"]
  node_remappings["Word remappings"]
end

node_user(("Mac user"))
node_target(("Active application"))

node_user -->|"presses hotkey"| node_keymonitor
node_keymonitor -->|"delivers keys"| node_transcription
node_transcription -->|"processes events"| node_hotkeylogic
node_transcription -->|"controls recording"| node_recording
node_recording -->|"uses capture"| node_capture
node_transcription -.->|"transcribes audio"| node_transcriptionclient
node_transcriptionclient -->|"dispatches engine"| node_parakeet
node_transcriptionclient -->|"prepares audio"| node_clip
node_transcription -.->|"pastes result"| node_pasteboard
node_pasteboard -->|"pastes text"| node_target
node_app -->|"starts lifecycle"| node_appfeature
node_settings -->|"fetches models"| node_modeldownload
node_modeldownload -->|"matches models"| node_modelmatcher
node_settings -->|"updates settings"| node_settingsmodel
node_transcription -->|"reads preferences"| node_settingsmodel
node_transcription -->|"saves transcript"| node_persistence
node_history -->|"manages records"| node_transcriptdata
node_transcription -->|"stores history data"| node_transcriptdata
node_settings -.->|"configures access"| node_permissions
node_settings -.->|"edits remappings"| node_remappings
node_transcription -->|"updates display"| node_indicator

click node_app "https://github.com/kitlangton/hex/blob/main/Hex/App/HexAppDelegate.swift"
click node_appfeature "https://github.com/kitlangton/hex/blob/main/Hex/Features/App/AppFeature.swift"
click node_transcription "https://github.com/kitlangton/hex/blob/main/Hex/Features/Transcription/TranscriptionFeature.swift"
click node_indicator "https://github.com/kitlangton/hex/blob/main/Hex/Features/Transcription/TranscriptionIndicatorView.swift"
click node_keymonitor "https://github.com/kitlangton/hex/blob/main/Hex/Clients/KeyEventMonitorClient.swift"
click node_hotkeylogic "https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/Logic/HotKeyProcessor.swift"
click node_recording "https://github.com/kitlangton/hex/blob/main/Hex/Clients/RecordingClient.swift"
click node_capture "https://github.com/kitlangton/hex/blob/main/Hex/Clients/SuperFastCaptureController.swift"
click node_transcriptionclient "https://github.com/kitlangton/hex/blob/main/Hex/Clients/TranscriptionClient.swift"
click node_parakeet "https://github.com/kitlangton/hex/blob/main/Hex/Clients/ParakeetClient.swift"
click node_clip "https://github.com/kitlangton/hex/blob/main/Hex/Clients/ParakeetClipPreparer.swift"
click node_pasteboard "https://github.com/kitlangton/hex/blob/main/Hex/Clients/PasteboardClient.swift"
click node_settings "https://github.com/kitlangton/hex/blob/main/Hex/Features/Settings/SettingsFeature.swift"
click node_settingsmodel "https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/Settings/HexSettings.swift"
click node_modeldownload "https://github.com/kitlangton/hex/blob/main/Hex/Features/Settings/ModelDownload/ModelDownloadFeature.swift"
click node_modelmatcher "https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/Logic/ModelPatternMatcher.swift"
click node_permissions "https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/PermissionClient/PermissionClient%2BLive.swift"
click node_history "https://github.com/kitlangton/hex/blob/main/Hex/Features/History/HistoryFeature.swift"
click node_transcriptdata "https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/Models/TranscriptionHistory.swift"
click node_persistence "https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/TranscriptPersistenceClient/TranscriptPersistenceClient.swift"
click node_remappings "https://github.com/kitlangton/hex/blob/main/Hex/Features/Remappings/WordRemappingsView.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_appfeature,node_transcription,node_indicator,node_user toneBlue
class node_keymonitor,node_hotkeylogic,node_recording,node_capture,node_transcriptionclient,node_parakeet,node_clip,node_pasteboard toneAmber
class node_settings,node_settingsmodel,node_modeldownload,node_modelmatcher toneMint
class node_permissions,node_history,node_transcriptdata,node_persistence,node_remappings toneRose
class node_target toneIndigo
```

## Components

### App workflow

- [App lifecycle](https://github.com/kitlangton/hex/blob/main/Hex/App/HexAppDelegate.swift): `Hex/App/HexAppDelegate.swift`
- [App feature](https://github.com/kitlangton/hex/blob/main/Hex/Features/App/AppFeature.swift): `Hex/Features/App/AppFeature.swift`
- [Transcription flow](https://github.com/kitlangton/hex/blob/main/Hex/Features/Transcription/TranscriptionFeature.swift): `Hex/Features/Transcription/TranscriptionFeature.swift`
- [Recording indicator](https://github.com/kitlangton/hex/blob/main/Hex/Features/Transcription/TranscriptionIndicatorView.swift): `Hex/Features/Transcription/TranscriptionIndicatorView.swift`

### Capture and transcription

- [Global key monitor](https://github.com/kitlangton/hex/blob/main/Hex/Clients/KeyEventMonitorClient.swift): `Hex/Clients/KeyEventMonitorClient.swift`
- [Hotkey processor](https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/Logic/HotKeyProcessor.swift): `HexCore/Sources/HexCore/Logic/HotKeyProcessor.swift`
- [Recording client](https://github.com/kitlangton/hex/blob/main/Hex/Clients/RecordingClient.swift): `Hex/Clients/RecordingClient.swift`
- [Fast audio capture](https://github.com/kitlangton/hex/blob/main/Hex/Clients/SuperFastCaptureController.swift): `Hex/Clients/SuperFastCaptureController.swift`
- [Transcription engines](https://github.com/kitlangton/hex/blob/main/Hex/Clients/TranscriptionClient.swift): `Hex/Clients/TranscriptionClient.swift`
- [Parakeet engine](https://github.com/kitlangton/hex/blob/main/Hex/Clients/ParakeetClient.swift): `Hex/Clients/ParakeetClient.swift`
- [Audio clip preparation](https://github.com/kitlangton/hex/blob/main/Hex/Clients/ParakeetClipPreparer.swift): `Hex/Clients/ParakeetClipPreparer.swift`
- [Paste and clipboard](https://github.com/kitlangton/hex/blob/main/Hex/Clients/PasteboardClient.swift): `Hex/Clients/PasteboardClient.swift`

### Settings and models

- [Settings feature](https://github.com/kitlangton/hex/blob/main/Hex/Features/Settings/SettingsFeature.swift): `Hex/Features/Settings/SettingsFeature.swift`
- [Settings state](https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/Settings/HexSettings.swift): `HexCore/Sources/HexCore/Settings/HexSettings.swift`
- [Model downloads](https://github.com/kitlangton/hex/blob/main/Hex/Features/Settings/ModelDownload/ModelDownloadFeature.swift): `Hex/Features/Settings/ModelDownload/ModelDownloadFeature.swift`
- [Model matching](https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/Logic/ModelPatternMatcher.swift): `HexCore/Sources/HexCore/Logic/ModelPatternMatcher.swift`

### Permissions and history

- [Permission client](https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/PermissionClient/PermissionClient%2BLive.swift): `HexCore/Sources/HexCore/PermissionClient/PermissionClient+Live.swift`
- [History feature](https://github.com/kitlangton/hex/blob/main/Hex/Features/History/HistoryFeature.swift): `Hex/Features/History/HistoryFeature.swift`
- [Transcript records](https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/Models/TranscriptionHistory.swift): `HexCore/Sources/HexCore/Models/TranscriptionHistory.swift`
- [Transcript persistence](https://github.com/kitlangton/hex/blob/main/HexCore/Sources/HexCore/TranscriptPersistenceClient/TranscriptPersistenceClient.swift): `HexCore/Sources/HexCore/TranscriptPersistenceClient/TranscriptPersistenceClient.swift`
- [Word remappings](https://github.com/kitlangton/hex/blob/main/Hex/Features/Remappings/WordRemappingsView.swift): `Hex/Features/Remappings/WordRemappingsView.swift`

### Other components

- **Mac user**
- **Active application**

## Connections

- Mac user → Global key monitor: presses hotkey
- Global key monitor → Transcription flow: delivers keys (evidence: `Hex/Features/Transcription/TranscriptionFeature.swift`)
- Transcription flow → Hotkey processor: processes events (evidence: `Hex/Features/Transcription/TranscriptionFeature.swift`)
- Transcription flow → Recording client: controls recording (evidence: `Hex/Features/Transcription/TranscriptionFeature.swift`)
- Recording client → Fast audio capture: uses capture (evidence: `Hex/Clients/RecordingClient.swift`)
- Transcription flow → Transcription engines: transcribes audio
- Transcription engines → Parakeet engine: dispatches engine (evidence: `Hex/Clients/TranscriptionClient.swift`)
- Transcription engines → Audio clip preparation: prepares audio (evidence: `Hex/Clients/TranscriptionClient.swift`)
- Transcription flow → Paste and clipboard: pastes result
- Paste and clipboard → Active application: pastes text
- App lifecycle → App feature: starts lifecycle (evidence: `Hex/App/HexApp.swift`)
- Settings feature → Model downloads: fetches models (evidence: `Hex/Features/Settings/SettingsFeature.swift`)
- Model downloads → Model matching: matches models (evidence: `Hex/Features/Settings/ModelDownload/ModelDownloadFeature.swift`)
- Settings feature → Settings state: updates settings (evidence: `Hex/Features/Settings/SettingsFeature.swift`)
- Transcription flow → Settings state: reads preferences (evidence: `Hex/Features/Transcription/TranscriptionFeature.swift`)
- Transcription flow → Transcript persistence: saves transcript (evidence: `Hex/Features/Transcription/TranscriptionFeature.swift`)
- History feature → Transcript records: manages records (evidence: `Hex/Features/History/HistoryFeature.swift`)
- Transcription flow → Transcript records: stores history data (evidence: `Hex/Features/Transcription/TranscriptionFeature.swift`)
- Settings feature → Permission client: configures access
- Settings feature → Word remappings: edits remappings
- Transcription flow → Recording indicator: updates display (evidence: `Hex/Features/Transcription/TranscriptionFeature.swift`)
