# shlgd/superdictate architecture

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

- Interactive diagram: https://gitdiagram.com/shlgd/superdictate
- Repository: https://github.com/shlgd/superdictate

## Overview

SuperDictate is a native macOS push-to-talk dictation app. The user invokes a global shortcut, records speech, gets a local transcription, and inserts the result; configurable post-processing may optionally send the completed text to an OpenAI-compatible service. The README also documents model selection and downloads, audio-file transcription, history, settings, and user-initiated updates. The sampled sources show model/runtime management and the Python ASR protocol; UI, shortcut handling, insertion, and other app behavior are represented from README documentation, with their enclosing source path rather than an assumed implementation detail.

Main entry points: [`swift/Sources/Parakey/LocalSpeechModels.swift`](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/LocalSpeechModels.swift) (Model manager), [`swift/Sources/Parakey/main.swift`](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift) (Native app), [`swift/Resources/local-asr.py`](https://github.com/shlgd/superdictate/blob/main/swift/Resources/local-asr.py) (Local ASR runtime), [`swift/Sources/Parakey/PackagedSpeechRuntime.swift`](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/PackagedSpeechRuntime.swift) (Speech runtime installer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and transcription"]
  node_app["Native app<br/>[main.swift]"]
  node_shortcuts["Global shortcuts<br/>[main.swift]"]
  node_recording["Microphone recording<br/>[main.swift]"]
  node_asrclient["ASR process client"]
  node_asr["Local ASR runtime<br/>[local-asr.py]"]
  node_postprocess["Text cleanup<br/>[main.swift]"]
  node_insertion["Text insertion<br/>[main.swift]"]
end

subgraph group_models["Speech models"]
  node_modelmanager["Model manager"]
  node_modelstorage[("Local model storage")]
  node_speechruntime["Speech runtime installer"]
  node_pythonruntime["Managed Python runtime"]
end

subgraph group_experience["App experience"]
  node_history[("Transcription history<br/>[main.swift]")]
  node_audioimport["Audio-file import<br/>[main.swift]"]
  node_settings["Settings and panels<br/>[main.swift]"]
end

subgraph group_maintenance["Updates and diagnostics"]
  node_updates["App updater<br/>[main.swift]"]
  node_signing["Update signature validation"]
  node_diagnostics[("Download diagnostics")]
end

node_user(("User"))
node_microphone(("macOS microphone"))
node_ai{{"OpenAI-compatible service"}}
node_modelhub{{"Model download service"}}
node_github{{"GitHub releases"}}

node_user -->|"invokes"| node_shortcuts
node_shortcuts -->|"dispatches"| node_app
node_app -->|"starts recording"| node_recording
node_microphone -->|"provides audio"| node_recording
node_recording -->|"submits audio"| node_asrclient
node_asrclient -->|"launches and requests"| node_asr
node_asr -->|"reads weights"| node_modelstorage
node_asrclient -->|"returns transcript"| node_postprocess
node_postprocess -.->|"sends text"| node_ai
node_postprocess -->|"passes text"| node_insertion
node_insertion -->|"inserts text"| node_user
node_app -->|"stores transcripts"| node_history
node_user -->|"selects audio"| node_audioimport
node_audioimport -->|"submits audio"| node_asrclient
node_audioimport -->|"saves transcripts"| node_history
node_user -->|"configures"| node_settings
node_settings -->|"applies preferences"| node_app
node_app -->|"manages models"| node_modelmanager
node_modelmanager -->|"reads and writes"| node_modelstorage
node_modelmanager -->|"ensures runtime"| node_speechruntime
node_modelmanager -.->|"prepares fallback runtime"| node_pythonruntime
node_speechruntime -->|"downloads runtime"| node_github
node_pythonruntime -->|"downloads interpreter"| node_github
node_asr -->|"downloads model assets"| node_modelhub
node_user -->|"requests update"| node_updates
node_updates -->|"downloads release"| node_github
node_updates -->|"validates candidate"| node_signing
node_modelmanager -->|"records download events"| node_diagnostics

click node_app "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_shortcuts "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_recording "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_asrclient "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/LocalSpeechModels.swift"
click node_asr "https://github.com/shlgd/superdictate/blob/main/swift/Resources/local-asr.py"
click node_postprocess "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_insertion "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_modelmanager "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/LocalSpeechModels.swift"
click node_modelstorage "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/LocalSpeechStorage.swift"
click node_speechruntime "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/PackagedSpeechRuntime.swift"
click node_pythonruntime "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/ManagedSpeechRuntime.swift"
click node_history "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_audioimport "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_settings "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_updates "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift"
click node_signing "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/UpdateSigning.swift"
click node_diagnostics "https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/DownloadDiagnostics.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_shortcuts,node_recording,node_asrclient,node_asr,node_postprocess,node_insertion,node_user toneBlue
class node_modelmanager,node_modelstorage,node_speechruntime,node_pythonruntime toneAmber
class node_history,node_audioimport,node_settings toneMint
class node_updates,node_signing,node_diagnostics toneRose
class node_microphone,node_ai,node_modelhub,node_github toneIndigo
```

## Components

### Capture and transcription

- [Native app](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`
- [Global shortcuts](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`
- [Microphone recording](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`
- [ASR process client](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/LocalSpeechModels.swift): `swift/Sources/Parakey/LocalSpeechModels.swift`
- [Local ASR runtime](https://github.com/shlgd/superdictate/blob/main/swift/Resources/local-asr.py): `swift/Resources/local-asr.py`
- [Text cleanup](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`
- [Text insertion](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`

### Speech models

- [Model manager](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/LocalSpeechModels.swift): `swift/Sources/Parakey/LocalSpeechModels.swift`
- [Local model storage](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/LocalSpeechStorage.swift): `swift/Sources/Parakey/LocalSpeechStorage.swift`
- [Speech runtime installer](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/PackagedSpeechRuntime.swift): `swift/Sources/Parakey/PackagedSpeechRuntime.swift`
- [Managed Python runtime](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/ManagedSpeechRuntime.swift): `swift/Sources/Parakey/ManagedSpeechRuntime.swift`

### App experience

- [Transcription history](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`
- [Audio-file import](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`
- [Settings and panels](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`

### Updates and diagnostics

- [App updater](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/main.swift): `swift/Sources/Parakey/main.swift`
- [Update signature validation](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/UpdateSigning.swift): `swift/Sources/Parakey/UpdateSigning.swift`
- [Download diagnostics](https://github.com/shlgd/superdictate/blob/main/swift/Sources/Parakey/DownloadDiagnostics.swift): `swift/Sources/Parakey/DownloadDiagnostics.swift`

### Other components

- **User**
- **macOS microphone**
- **OpenAI-compatible service**
- **Model download service**
- **GitHub releases**

## Connections

- User → Global shortcuts: invokes
- Global shortcuts → Native app: dispatches
- Native app → Microphone recording: starts recording
- macOS microphone → Microphone recording: provides audio
- Microphone recording → ASR process client: submits audio
- ASR process client → Local ASR runtime: launches and requests
- Local ASR runtime → Local model storage: reads weights
- ASR process client → Text cleanup: returns transcript
- Text cleanup → OpenAI-compatible service: sends text
- Text cleanup → Text insertion: passes text
- Text insertion → User: inserts text
- Native app → Transcription history: stores transcripts
- User → Audio-file import: selects audio
- Audio-file import → ASR process client: submits audio
- Audio-file import → Transcription history: saves transcripts
- User → Settings and panels: configures
- Settings and panels → Native app: applies preferences
- Native app → Model manager: manages models
- Model manager → Local model storage: reads and writes
- Model manager → Speech runtime installer: ensures runtime
- Model manager → Managed Python runtime: prepares fallback runtime
- Speech runtime installer → GitHub releases: downloads runtime
- Managed Python runtime → GitHub releases: downloads interpreter
- Local ASR runtime → Model download service: downloads model assets
- User → App updater: requests update
- App updater → GitHub releases: downloads release
- App updater → Update signature validation: validates candidate
- Model manager → Download diagnostics: records download events