# mehmetvarol/katip architecture

> Architecture diagram of the GitHub repository mehmetvarol/katip, 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/mehmetvarol/katip
- Repository: https://github.com/mehmetvarol/katip

## Overview

Katip is a local-first macOS dictation app for turning Turkish speech mixed with English technical terms into text at the focused cursor. The main workflow starts from the menu-bar icon, global hotkey, or floating card; the controller captures and segments audio, sends it to a locally loaded Whisper model, applies terminology corrections and text expansions, then injects the result and records history. Other documented branches include replaying saved recordings, app-specific language and glossary rules, settings, and user-initiated updates. Relationships reflect the README and sampled excerpts; unsampled subsystem wiring is not inferred beyond those documented capabilities.

Main entry points: [`app/Sources/Katip/DictationController.swift`](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/DictationController.swift) (Dictation controller), [`app/Sources/Katip/Transcriber.swift`](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Transcriber.swift) (Whisper transcriber), [`app/Sources/Katip/KatipApp.swift`](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/KatipApp.swift) (App lifecycle), [`app/Sources/Katip/StatusMenu.swift`](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/StatusMenu.swift) (Status menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction"]
  node_app["App lifecycle<br/>[KatipApp.swift]"]
  node_status["Status menu<br/>[StatusMenu.swift]"]
  node_hotkey["Global hotkey<br/>[Hotkey.swift]"]
  node_hud["Floating card<br/>[HUDPanel.swift]"]
  node_historywindow["History window"]
end

subgraph group_dictation["Dictation"]
  node_controller["Dictation controller"]
  node_recorder["Audio capture"]
  node_segmenter["Speech segmenter"]
  node_transcriber["Whisper transcriber<br/>[Transcriber.swift]"]
  node_stitcher["Segment stitcher<br/>[Stitcher.swift]"]
  node_injector["Text injection<br/>[TextInjector.swift]"]
end

subgraph group_text["Text processing"]
  node_glossary["Glossary<br/>[Glossary.swift]"]
  node_fuzzy["Term correction<br/>[FuzzyTerms.swift]"]
  node_snippets["Text snippets<br/>[Snippets.swift]"]
  node_profiles["App profiles<br/>[AppProfiles.swift]"]
end

subgraph group_state["Local state"]
  node_history[("Dictation history<br/>[History.swift]")]
  node_recordings[("Saved recordings<br/>[Recordings.swift]")]
end

subgraph group_support["App support"]
  node_permissions["Permissions<br/>[Permissions.swift]"]
  node_updater["Manual updater<br/>[Updater.swift]"]
  node_loginitem["Login item<br/>[LoginItem.swift]"]
end

node_user(("User"))
node_whisperkit["WhisperKit"]
node_modelhost["Model download"]
node_github["GitHub releases"]

node_user -->|"clicks"| node_status
node_user -->|"presses"| node_hotkey
node_user -->|"uses"| node_hud
node_app -->|"creates"| node_status
node_app -->|"starts"| node_hotkey
node_app -->|"configures"| node_controller
node_status -->|"controls"| node_controller
node_hotkey -->|"signals"| node_controller
node_hud -->|"actions"| node_controller
node_controller -->|"captures audio"| node_recorder
node_controller -->|"segments audio"| node_segmenter
node_controller -->|"transcribes"| node_transcriber
node_transcriber -->|"runs inference"| node_whisperkit
node_transcriber -.->|"downloads model"| node_modelhost
node_transcriber -->|"reads terms"| node_glossary
node_transcriber -->|"stitches results"| node_stitcher
node_transcriber -->|"corrects terms"| node_fuzzy
node_transcriber -->|"expands phrases"| node_snippets
node_controller -->|"applies rules"| node_profiles
node_controller -->|"injects text"| node_injector
node_controller -->|"saves result"| node_history
node_controller -->|"saves audio"| node_recordings
node_historywindow -->|"reads entries"| node_history
node_historywindow -->|"requests replay"| node_controller
node_controller -->|"retranscribes audio"| node_transcriber
node_app -->|"checks access"| node_permissions
node_status -->|"checks on request"| node_updater
node_updater -.->|"fetches release"| node_github
node_app -->|"configures launch"| node_loginitem

click node_app "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/KatipApp.swift"
click node_status "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/StatusMenu.swift"
click node_hotkey "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Hotkey.swift"
click node_hud "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/HUDPanel.swift"
click node_controller "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/DictationController.swift"
click node_recorder "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/AudioRecorder.swift"
click node_segmenter "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/SpeechSegmenter.swift"
click node_transcriber "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Transcriber.swift"
click node_stitcher "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Stitcher.swift"
click node_injector "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/TextInjector.swift"
click node_glossary "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Glossary.swift"
click node_fuzzy "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/FuzzyTerms.swift"
click node_snippets "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Snippets.swift"
click node_profiles "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/AppProfiles.swift"
click node_history "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/History.swift"
click node_recordings "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Recordings.swift"
click node_historywindow "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/HistoryWindow.swift"
click node_permissions "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Permissions.swift"
click node_updater "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Updater.swift"
click node_loginitem "https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/LoginItem.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_status,node_hotkey,node_hud,node_historywindow,node_user toneBlue
class node_controller,node_recorder,node_segmenter,node_transcriber,node_stitcher,node_injector toneAmber
class node_glossary,node_fuzzy,node_snippets,node_profiles toneMint
class node_history,node_recordings toneRose
class node_permissions,node_updater,node_loginitem,node_whisperkit,node_modelhost,node_github toneIndigo
```

## Components

### Interaction

- [App lifecycle](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/KatipApp.swift): `app/Sources/Katip/KatipApp.swift`
- [Status menu](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/StatusMenu.swift): `app/Sources/Katip/StatusMenu.swift`
- [Global hotkey](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Hotkey.swift): `app/Sources/Katip/Hotkey.swift`
- [Floating card](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/HUDPanel.swift): `app/Sources/Katip/HUDPanel.swift`
- [History window](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/HistoryWindow.swift): `app/Sources/Katip/HistoryWindow.swift`

### Dictation

- [Dictation controller](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/DictationController.swift): `app/Sources/Katip/DictationController.swift`
- [Audio capture](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/AudioRecorder.swift): `app/Sources/Katip/AudioRecorder.swift`
- [Speech segmenter](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/SpeechSegmenter.swift): `app/Sources/Katip/SpeechSegmenter.swift`
- [Whisper transcriber](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Transcriber.swift): `app/Sources/Katip/Transcriber.swift`
- [Segment stitcher](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Stitcher.swift): `app/Sources/Katip/Stitcher.swift`
- [Text injection](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/TextInjector.swift): `app/Sources/Katip/TextInjector.swift`

### Text processing

- [Glossary](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Glossary.swift): `app/Sources/Katip/Glossary.swift`
- [Term correction](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/FuzzyTerms.swift): `app/Sources/Katip/FuzzyTerms.swift`
- [Text snippets](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Snippets.swift): `app/Sources/Katip/Snippets.swift`
- [App profiles](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/AppProfiles.swift): `app/Sources/Katip/AppProfiles.swift`

### Local state

- [Dictation history](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/History.swift): `app/Sources/Katip/History.swift`
- [Saved recordings](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Recordings.swift): `app/Sources/Katip/Recordings.swift`

### App support

- [Permissions](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Permissions.swift): `app/Sources/Katip/Permissions.swift`
- [Manual updater](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/Updater.swift): `app/Sources/Katip/Updater.swift`
- [Login item](https://github.com/mehmetvarol/katip/blob/main/app/Sources/Katip/LoginItem.swift): `app/Sources/Katip/LoginItem.swift`

### Other components

- **User**
- **WhisperKit**
- **Model download**
- **GitHub releases**

## Connections

- User → Status menu: clicks
- User → Global hotkey: presses
- User → Floating card: uses
- App lifecycle → Status menu: creates
- App lifecycle → Global hotkey: starts
- App lifecycle → Dictation controller: configures
- Status menu → Dictation controller: controls
- Global hotkey → Dictation controller: signals
- Floating card → Dictation controller: actions
- Dictation controller → Audio capture: captures audio
- Dictation controller → Speech segmenter: segments audio
- Dictation controller → Whisper transcriber: transcribes
- Whisper transcriber → WhisperKit: runs inference
- Whisper transcriber → Model download: downloads model
- Whisper transcriber → Glossary: reads terms
- Whisper transcriber → Segment stitcher: stitches results
- Whisper transcriber → Term correction: corrects terms
- Whisper transcriber → Text snippets: expands phrases
- Dictation controller → App profiles: applies rules
- Dictation controller → Text injection: injects text
- Dictation controller → Dictation history: saves result
- Dictation controller → Saved recordings: saves audio
- History window → Dictation history: reads entries
- History window → Dictation controller: requests replay
- Dictation controller → Whisper transcriber: retranscribes audio
- App lifecycle → Permissions: checks access
- Status menu → Manual updater: checks on request
- Manual updater → GitHub releases: fetches release
- App lifecycle → Login item: configures launch