# beingpax/voiceink architecture

> Architecture diagram of the GitHub repository beingpax/voiceink, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beingpax/voiceink
- Repository: https://github.com/beingpax/voiceink

## Overview

##### Main Components
- Application Entry Point: Represent the AppDelegate (found in VoiceInk/AppDelegate.swift) which is where the app lifecycle begins.
- UI Layer: Include the Views (entire VoiceInk/Views directory with ContentView, Onboarding, Settings, Metrics, etc.) and ViewModels (VoiceInk/ViewModels) that represent the presentation layer. Also show the Components (subdirectory within Views) like ProBadge, TrialMessageView, VideoCTAView, etc.
- Business & Domain Logic:
- Services: Create a separate component for the “Services” directory. This encapsulates critical functionalities (e.g., AIEnhancementService, AIService, AudioTranscriptionService, BrowserURLService, ScreenCaptureService, and others). These handle tasks like transcription, AI prompt management, audio processing, audio transcription, window management, and even integration with external utilities.
- Models: Include the Models directory (CustomPrompt, PowerModeConfig, PredefinedPrompts, etc.) to show data structures and domain objects.
- Audio and Media Management: Highlight specialized files such as Recorder.swift, MediaController.swift, AudioDeviceManager.swift, AudioTranscriptionManager.swift, AudioProcessor.swift, and SoundManager.swift.
- Auxiliary Components:
- ClipboardManager.swift and HotkeyManager.swift – these are used to support user input and register global shortcuts for functionalities.
- WindowManager.swift – likely managing app windows (menu bar, mini-recorder, notch recorder views).
- Whisper Directory: Include a component showing how the whisper-based transcription (using LibWhisper, WhisperError, WhisperPrompt etc.) is abstracted for handling deep transcription logic.

##### External and Third-party Dependencies
- Use of external libraries like Sparkle (for updates), KeyboardShortcuts, and LaunchAtLogin.
- Integration with open-source AI models (whisper.cpp) which drive the core transcription functionality.
- Voice recording and transcription architecture that supports “local AI” processing for privacy.

##### Defining Relationships and Interactions
- Application Lifecycle Flow: Illustrate how the AppDelegate initializes core services, loads the UI, and then dispatches interactions.
- Configuration and Helpers: Show that Settings, AudioDeviceConfiguration, UserDefaultsManager, and ClipboardManager are supporting services that maintain user preferences and hardware configurations.

##### Architectural Patterns and Design Principles
- MVC/MVVM: Highlight the use of common macOS patterns such as separating UI (Views) from business logic (ViewModels) and domain services.
- Modular Design: The clear separation into directories such as Models, Views, and Services suggests a modular architecture, making it easier to extend and maintain.
- Dependency Management: Indicate use of Swift packages (via swiftpm) and Xcode project structure which abstracts configuration and builds scripts, suggesting that configurations (like build and deployment, including the use of Sparkle for updates) are taken into account.

## Diagram (Mermaid)

```mermaid
graph TD
    app["AppDelegate"]:::service

    subgraph "UI Layer"
        ui1["Views"]:::ui
        ui2["ViewModels"]:::ui
    end

    subgraph "Business & Domain Logic"
        biz1["Services"]:::service
        biz2["Models"]:::service
    end

    subgraph "Audio & Media Management"
        audio1["Recorder"]:::audio
        audio2["Media Controller"]:::audio
        audio3["Audio Device Manager"]:::audio
        audio4["Audio Processor"]:::audio
        audio5["Audio Transcription Manager"]:::audio
        audio6["Sound Manager"]:::audio
    end

    subgraph "Auxiliary Components"
        aux1["ClipboardManager"]:::aux
        aux2["HotkeyManager"]:::aux
        aux3["WindowManager"]:::aux
    end

    whisper["Whisper Module"]:::service

    subgraph "External Dependencies"
        ext1["Sparkle"]:::external
        ext2["KeyboardShortcuts"]:::external
        ext3["LaunchAtLogin"]:::external
    end

    %% Application Lifecycle Flow
    app -->|"initUI"| ui1
    app -->|"initServices"| biz1

    %% UI Layer Interaction
    ui1 -->|"bindsModel"| ui2
    ui2 -->|"callsService"| biz1

    %% Auxiliary triggers and recording pipeline
    aux2 -->|"trigger"| audio1
    audio1 -->|"sendsAudio"| audio2
    audio2 -->|"checkDevice"| audio3
    audio3 -->|"deviceData"| audio4
    audio4 -->|"transcribeAudio"| audio5

    %% Audio to Business Logic flow
    audio5 -->|"useService"| biz1
    audio5 -->|"storeTranscription"| biz2

    %% Service and Whisper integration
    biz1 -->|"useWhisper"| whisper

    %% External Dependencies integration
    biz1 -->|"updateCheck"| ext1
    biz1 -->|"autoStart"| ext3
    ext2 -->|"registerKeys"| aux2

    %% Auxiliary support to UI
    aux3 -->|"manageWindows"| ui1
    aux1 -->|"copyData"| ui2

    %% Click Events
    click app "https://github.com/beingpax/voiceink/blob/main/VoiceInk/AppDelegate.swift"
    click ui1 "https://github.com/beingpax/voiceink/tree/main/VoiceInk/Views"
    click ui2 "https://github.com/beingpax/voiceink/tree/main/VoiceInk/ViewModels"
    click biz1 "https://github.com/beingpax/voiceink/tree/main/VoiceInk/Services"
    click biz2 "https://github.com/beingpax/voiceink/tree/main/VoiceInk/Models"
    click audio1 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/Recorder.swift"
    click audio2 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/MediaController.swift"
    click audio3 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/Services/AudioDeviceManager.swift"
    click audio4 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/Services/AudioProcessor.swift"
    click audio5 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/Services/AudioTranscriptionManager.swift"
    click audio6 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/SoundManager.swift"
    click aux1 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/ClipboardManager.swift"
    click aux2 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/HotkeyManager.swift"
    click aux3 "https://github.com/beingpax/voiceink/blob/main/VoiceInk/WindowManager.swift"
    click whisper "https://github.com/beingpax/voiceink/tree/main/VoiceInk/Whisper"

    %% Styles
    classDef ui fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef service fill:#D4F4DD,stroke:#333,stroke-width:2px;
    classDef audio fill:#FFF5BA,stroke:#333,stroke-width:2px;
    classDef aux fill:#FADADD,stroke:#333,stroke-width:2px;
    classDef external fill:#DCEDF7,stroke:#333,stroke-width:2px;
```
