# moona3k/macparakeet architecture

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

- Interactive diagram: https://gitdiagram.com/moona3k/macparakeet
- Repository: https://github.com/moona3k/macparakeet

## Overview

MacParakeet is a local-first macOS voice app for system-wide dictation, media transcription, and meeting capture, with optional networked AI. The main paths take spoken or imported audio through capture and speech recognition to cleaned, saved text; meeting recording additionally supports live notes and later analysis. The graph also preserves calendar automation, editing/library, and CLI capabilities described in the README. Edges use README evidence for documented product flows; source excerpts are incomplete, so finer implementation-level calls are omitted.

Main entry points: [`Sources/MacParakeetCore/STT/STTRuntime.swift`](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/STT/STTRuntime.swift) (Speech engines), [`Sources/MacParakeet/App/MeetingRecordingFlowCoordinator.swift`](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/App/MeetingRecordingFlowCoordinator.swift) (Meeting workflow), [`Sources/MacParakeet/Views/MeetingRecording/MeetingRecordingPanelView.swift`](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/MeetingRecording/MeetingRecordingPanelView.swift) (Meeting workspace), [`Sources/MacParakeetCore/Services/LLM/LLMService.swift`](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Services/LLM/LLMService.swift) (AI services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["App interaction"]
  node_app["Mac app"]
  node_hotkey["Global hotkeys"]
  node_transcribe_ui["Transcribe UI"]
end

subgraph group_audio["Audio and speech"]
  node_audio_capture["Audio capture"]
  node_meeting_capture["Meeting capture"]
  node_stt["Speech engines<br/>[STTRuntime.swift]"]
end

subgraph group_results["Transcript and library"]
  node_text_pipeline["Text cleanup"]
  node_library["Transcription library"]
  node_transcript["Transcript editor"]
  node_transcription_store[("Transcription storage")]
end

subgraph group_meeting["Meeting workflows"]
  node_meeting_flow["Meeting workflow"]
  node_calendar["Calendar triggers"]
  node_meeting_view["Meeting workspace"]
end

subgraph group_intelligence["AI and automation"]
  node_llm["AI services<br/>[LLMService.swift]"]
  node_ask["Ask workspace"]
  node_transforms["Text transforms"]
  node_cli["CLI commands"]
end

node_user(("User"))
node_calendar_service["macOS Calendar"]

node_user -->|"uses"| node_app
node_user -->|"presses"| node_hotkey
node_hotkey -->|"starts capture"| node_audio_capture
node_user -->|"imports media"| node_transcribe_ui
node_transcribe_ui -->|"submits audio"| node_stt
node_audio_capture -->|"transcribes locally"| node_stt
node_stt -->|"cleans text"| node_text_pipeline
node_text_pipeline -->|"saves result"| node_transcription_store
node_transcription_store -->|"provides results"| node_library
node_library -->|"opens result"| node_transcript
node_user -->|"records meeting"| node_meeting_view
node_meeting_view -->|"controls recording"| node_meeting_flow
node_meeting_flow -->|"captures audio"| node_meeting_capture
node_meeting_capture -->|"transcribes locally"| node_stt
node_meeting_flow -->|"shows live transcript"| node_meeting_view
node_calendar_service -->|"provides events"| node_calendar
node_calendar -->|"can auto-start"| node_meeting_flow
node_meeting_view -->|"requests analysis"| node_llm
node_ask -->|"asks questions"| node_llm
node_user -->|"selects text"| node_transforms
node_transforms -->|"requests transform"| node_llm
node_user -->|"runs command"| node_cli
node_cli -->|"transcribes media"| node_stt

click node_app "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/MacParakeetApp.swift"
click node_hotkey "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Hotkey/HotkeyManager.swift"
click node_transcribe_ui "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/Transcription/TranscribeView.swift"
click node_audio_capture "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Audio/MicrophoneEnginePlatform.swift"
click node_meeting_capture "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Audio/MeetingAudioCaptureService.swift"
click node_stt "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/STT/STTRuntime.swift"
click node_text_pipeline "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/TextProcessing/TextProcessingPipeline.swift"
click node_library "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/Transcription/TranscriptionLibraryView.swift"
click node_transcript "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/Transcription/TranscriptResultView.swift"
click node_transcription_store "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Database/TranscriptionRepository.swift"
click node_meeting_flow "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/App/MeetingRecordingFlowCoordinator.swift"
click node_calendar "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Calendar/MeetingMonitor.swift"
click node_meeting_view "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/MeetingRecording/MeetingRecordingPanelView.swift"
click node_llm "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Services/LLM/LLMService.swift"
click node_ask "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/Ask/AskWorkspaceView.swift"
click node_transforms "https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/App/TransformsCoordinator.swift"
click node_cli "https://github.com/moona3k/macparakeet/blob/main/Sources/CLI/Commands/TranscribeCommand.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_hotkey,node_transcribe_ui,node_user toneBlue
class node_audio_capture,node_meeting_capture,node_stt toneAmber
class node_text_pipeline,node_library,node_transcript,node_transcription_store toneMint
class node_meeting_flow,node_calendar,node_meeting_view toneRose
class node_llm,node_ask,node_transforms,node_cli,node_calendar_service toneIndigo
```

## Components

### App interaction

- [Mac app](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/MacParakeetApp.swift): `Sources/MacParakeet/MacParakeetApp.swift`
- [Global hotkeys](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Hotkey/HotkeyManager.swift): `Sources/MacParakeet/Hotkey/HotkeyManager.swift`
- [Transcribe UI](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/Transcription/TranscribeView.swift): `Sources/MacParakeet/Views/Transcription/TranscribeView.swift`

### Audio and speech

- [Audio capture](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Audio/MicrophoneEnginePlatform.swift): `Sources/MacParakeetCore/Audio/MicrophoneEnginePlatform.swift`
- [Meeting capture](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Audio/MeetingAudioCaptureService.swift): `Sources/MacParakeetCore/Audio/MeetingAudioCaptureService.swift`
- [Speech engines](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/STT/STTRuntime.swift): `Sources/MacParakeetCore/STT/STTRuntime.swift`

### Transcript and library

- [Text cleanup](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/TextProcessing/TextProcessingPipeline.swift): `Sources/MacParakeetCore/TextProcessing/TextProcessingPipeline.swift`
- [Transcription library](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/Transcription/TranscriptionLibraryView.swift): `Sources/MacParakeet/Views/Transcription/TranscriptionLibraryView.swift`
- [Transcript editor](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/Transcription/TranscriptResultView.swift): `Sources/MacParakeet/Views/Transcription/TranscriptResultView.swift`
- [Transcription storage](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Database/TranscriptionRepository.swift): `Sources/MacParakeetCore/Database/TranscriptionRepository.swift`

### Meeting workflows

- [Meeting workflow](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/App/MeetingRecordingFlowCoordinator.swift): `Sources/MacParakeet/App/MeetingRecordingFlowCoordinator.swift`
- [Calendar triggers](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Calendar/MeetingMonitor.swift): `Sources/MacParakeetCore/Calendar/MeetingMonitor.swift`
- [Meeting workspace](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/MeetingRecording/MeetingRecordingPanelView.swift): `Sources/MacParakeet/Views/MeetingRecording/MeetingRecordingPanelView.swift`

### AI and automation

- [AI services](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeetCore/Services/LLM/LLMService.swift): `Sources/MacParakeetCore/Services/LLM/LLMService.swift`
- [Ask workspace](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/Views/Ask/AskWorkspaceView.swift): `Sources/MacParakeet/Views/Ask/AskWorkspaceView.swift`
- [Text transforms](https://github.com/moona3k/macparakeet/blob/main/Sources/MacParakeet/App/TransformsCoordinator.swift): `Sources/MacParakeet/App/TransformsCoordinator.swift`
- [CLI commands](https://github.com/moona3k/macparakeet/blob/main/Sources/CLI/Commands/TranscribeCommand.swift): `Sources/CLI/Commands/TranscribeCommand.swift`

### Other components

- **User**
- **macOS Calendar**

## Connections

- User → Mac app: uses (evidence: `README.md`)
- User → Global hotkeys: presses (evidence: `README.md`)
- Global hotkeys → Audio capture: starts capture (evidence: `README.md`)
- User → Transcribe UI: imports media (evidence: `README.md`)
- Transcribe UI → Speech engines: submits audio (evidence: `README.md`)
- Audio capture → Speech engines: transcribes locally (evidence: `README.md`)
- Speech engines → Text cleanup: cleans text (evidence: `README.md`)
- Text cleanup → Transcription storage: saves result (evidence: `README.md`)
- Transcription storage → Transcription library: provides results (evidence: `README.md`)
- Transcription library → Transcript editor: opens result (evidence: `README.md`)
- User → Meeting workspace: records meeting (evidence: `README.md`)
- Meeting workspace → Meeting workflow: controls recording (evidence: `README.md`)
- Meeting workflow → Meeting capture: captures audio (evidence: `README.md`)
- Meeting capture → Speech engines: transcribes locally (evidence: `README.md`)
- Meeting workflow → Meeting workspace: shows live transcript (evidence: `README.md`)
- macOS Calendar → Calendar triggers: provides events (evidence: `README.md`)
- Calendar triggers → Meeting workflow: can auto-start (evidence: `README.md`)
- Meeting workspace → AI services: requests analysis (evidence: `README.md`)
- Ask workspace → AI services: asks questions (evidence: `README.md`)
- User → Text transforms: selects text (evidence: `README.md`)
- Text transforms → AI services: requests transform (evidence: `README.md`)
- User → CLI commands: runs command (evidence: `README.md`)
- CLI commands → Speech engines: transcribes media (evidence: `README.md`)
