# tk88101/azathoths-whisper architecture

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

- Interactive diagram: https://gitdiagram.com/tk88101/azathoths-whisper
- Repository: https://github.com/tk88101/azathoths-whisper

## Overview

Azathoth’s Whisper is a macOS SwiftUI app that monitors Music.app, fetches lyrics for the playing track, and embeds them in its audio-file metadata. Its user workflow runs from track detection through lyrics lookup and write-back; the editor and batch-import flows use different lookup policies. The app also provides queue-aware lyrics and a display-only Cover Flow, artwork caching, settings, and localization. Edges are limited to relationships supported by the README or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`AzathothsWhisper/App/AppModel.swift`](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/App/AppModel.swift) (App coordinator), [`AzathothsWhisper/Features/Shell/RootView.swift`](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Shell/RootView.swift) (App interface), [`AzathothsWhisper/Services/Music/MusicControlling.swift`](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Music/MusicControlling.swift) (Music interface), [`AzathothsWhisper/Services/Artwork/ArtworkService.swift`](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Artwork/ArtworkService.swift) (Artwork service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App workflow"]
  node_appmodel["App coordinator<br/>[AppModel.swift]"]
  node_editor["Lyrics editor"]
  node_batch["Batch import"]
  node_lyricsflow["Queue lyrics"]
  node_deck["Deck snapshot<br/>[DeckSnapshot.swift]"]
  node_queue["Queue session<br/>[QueueSession.swift]"]
  node_covervm["Cover Flow state"]
end

subgraph group_lyrics["Lyrics lookup"]
  node_lyricsservice["Lyrics routing"]
  node_genius["Genius source<br/>[GeniusSource.swift]"]
  node_darklyrics["DarkLyrics source"]
  node_http["HTTP client<br/>[HTTPClient.swift]"]
end

subgraph group_music["Music integration"]
  node_monitor["Track monitor"]
  node_musicclient["Apple Events client"]
  node_musicprotocol["Music interface"]
  node_artwork["Artwork service"]
  node_artmemory["Memory cache"]
  node_artdisk[("Disk cache")]
end

subgraph group_views["User experience"]
  node_root["App interface<br/>[RootView.swift]"]
  node_batchview["Batch screen<br/>[BatchView.swift]"]
  node_lyricsview["Lyrics screen"]
end

subgraph group_config["Settings and assets"]
  node_settings["Settings state"]
  node_configstore[("Configuration<br/>[ConfigStore.swift]")]
  node_language["Language manager"]
end

node_user(("User"))
node_musicapp["Music.app"]
node_geniusapi["Genius API"]
node_darklyricsweb["DarkLyrics"]

node_user -->|"uses"| node_root
node_root -->|"binds state"| node_appmodel
node_root -->|"shows"| node_batchview
node_root -->|"shows"| node_lyricsview
node_appmodel -->|"starts and refreshes"| node_monitor
node_monitor -.->|"reads playback"| node_musicclient
node_musicclient -->|"implements"| node_musicprotocol
node_musicclient -->|"sends Apple Events"| node_musicapp
node_appmodel -->|"creates"| node_editor
node_appmodel -->|"creates"| node_batch
node_appmodel -->|"creates and starts"| node_lyricsflow
node_appmodel -->|"creates"| node_settings
node_editor -->|"fetches lyrics"| node_lyricsservice
node_batch -->|"fetches missing lyrics"| node_lyricsservice
node_editor -->|"reads and writes lyrics"| node_musicprotocol
node_batch -->|"loads and imports tracks"| node_musicprotocol
node_lyricsservice -->|"queries first"| node_genius
node_lyricsservice -->|"batch fallback"| node_darklyrics
node_genius -.->|"uses HTTP"| node_http
node_darklyrics -.->|"uses HTTP"| node_http
node_genius -.->|"queries"| node_geniusapi
node_darklyrics -.->|"queries"| node_darklyricsweb
node_lyricsflow -.->|"reads queue and playback"| node_musicprotocol
node_lyricsflow -.->|"builds deck"| node_deck
node_deck -->|"uses queue session"| node_queue
node_covervm -->|"gets deck state"| node_lyricsflow
node_appmodel -->|"creates"| node_covervm
node_covervm -->|"loads and prefetches"| node_artwork
node_artwork -->|"fetches artwork"| node_musicprotocol
node_artwork -->|"checks cache"| node_artmemory
node_artwork -->|"loads and stores"| node_artdisk
node_settings -.->|"reads and saves"| node_configstore
node_settings -.->|"manages language"| node_language
node_appmodel -->|"configures services"| node_configstore
node_settings -->|"presents settings"| node_root

click node_appmodel "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/App/AppModel.swift"
click node_monitor "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Music/NowPlayingMonitor.swift"
click node_musicclient "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Music/MusicAppleEventsClient.swift"
click node_musicprotocol "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Music/MusicControlling.swift"
click node_editor "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Editor/EditorViewModel.swift"
click node_batch "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Batch/BatchViewModel.swift"
click node_lyricsservice "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Lyrics/LyricsService.swift"
click node_genius "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Lyrics/GeniusSource.swift"
click node_darklyrics "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Lyrics/DarkLyricsSource.swift"
click node_http "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Infra/HTTPClient.swift"
click node_lyricsflow "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/LyricsFlow/LyricsFlowModel.swift"
click node_deck "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/LyricsFlow/DeckSnapshot.swift"
click node_queue "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/LyricsFlow/QueueSession.swift"
click node_covervm "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/CoverFlow/CoverFlowViewModel.swift"
click node_artwork "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Artwork/ArtworkService.swift"
click node_artmemory "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Artwork/ArtworkMemoryCache.swift"
click node_artdisk "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Artwork/ArtworkDiskCache.swift"
click node_root "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Shell/RootView.swift"
click node_batchview "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Batch/BatchView.swift"
click node_lyricsview "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/LyricsFlow/LyricsFlowPageView.swift"
click node_settings "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Settings/SettingsViewModel.swift"
click node_configstore "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Config/ConfigStore.swift"
click node_language "https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Config/LanguageManager.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_appmodel,node_editor,node_batch,node_lyricsflow,node_deck,node_queue,node_covervm,node_user toneBlue
class node_lyricsservice,node_genius,node_darklyrics,node_http toneAmber
class node_monitor,node_musicclient,node_musicprotocol,node_artwork,node_artmemory,node_artdisk,node_geniusapi toneMint
class node_root,node_batchview,node_lyricsview toneRose
class node_settings,node_configstore,node_language,node_musicapp,node_darklyricsweb toneIndigo
```

## Components

### App workflow

- [App coordinator](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/App/AppModel.swift): `AzathothsWhisper/App/AppModel.swift`
- [Lyrics editor](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Editor/EditorViewModel.swift): `AzathothsWhisper/Features/Editor/EditorViewModel.swift`
- [Batch import](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Batch/BatchViewModel.swift): `AzathothsWhisper/Features/Batch/BatchViewModel.swift`
- [Queue lyrics](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/LyricsFlow/LyricsFlowModel.swift): `AzathothsWhisper/Features/LyricsFlow/LyricsFlowModel.swift`
- [Deck snapshot](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/LyricsFlow/DeckSnapshot.swift): `AzathothsWhisper/Features/LyricsFlow/DeckSnapshot.swift`
- [Queue session](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/LyricsFlow/QueueSession.swift): `AzathothsWhisper/Features/LyricsFlow/QueueSession.swift`
- [Cover Flow state](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/CoverFlow/CoverFlowViewModel.swift): `AzathothsWhisper/Features/CoverFlow/CoverFlowViewModel.swift`

### Lyrics lookup

- [Lyrics routing](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Lyrics/LyricsService.swift): `AzathothsWhisper/Services/Lyrics/LyricsService.swift`
- [Genius source](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Lyrics/GeniusSource.swift): `AzathothsWhisper/Services/Lyrics/GeniusSource.swift`
- [DarkLyrics source](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Lyrics/DarkLyricsSource.swift): `AzathothsWhisper/Services/Lyrics/DarkLyricsSource.swift`
- [HTTP client](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Infra/HTTPClient.swift): `AzathothsWhisper/Infra/HTTPClient.swift`

### Music integration

- [Track monitor](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Music/NowPlayingMonitor.swift): `AzathothsWhisper/Services/Music/NowPlayingMonitor.swift`
- [Apple Events client](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Music/MusicAppleEventsClient.swift): `AzathothsWhisper/Services/Music/MusicAppleEventsClient.swift`
- [Music interface](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Music/MusicControlling.swift): `AzathothsWhisper/Services/Music/MusicControlling.swift`
- [Artwork service](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Artwork/ArtworkService.swift): `AzathothsWhisper/Services/Artwork/ArtworkService.swift`
- [Memory cache](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Artwork/ArtworkMemoryCache.swift): `AzathothsWhisper/Services/Artwork/ArtworkMemoryCache.swift`
- [Disk cache](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Artwork/ArtworkDiskCache.swift): `AzathothsWhisper/Services/Artwork/ArtworkDiskCache.swift`

### User experience

- [App interface](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Shell/RootView.swift): `AzathothsWhisper/Features/Shell/RootView.swift`
- [Batch screen](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Batch/BatchView.swift): `AzathothsWhisper/Features/Batch/BatchView.swift`
- [Lyrics screen](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/LyricsFlow/LyricsFlowPageView.swift): `AzathothsWhisper/Features/LyricsFlow/LyricsFlowPageView.swift`

### Settings and assets

- [Settings state](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Features/Settings/SettingsViewModel.swift): `AzathothsWhisper/Features/Settings/SettingsViewModel.swift`
- [Configuration](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Config/ConfigStore.swift): `AzathothsWhisper/Services/Config/ConfigStore.swift`
- [Language manager](https://github.com/tk88101/azathoths-whisper/blob/main/AzathothsWhisper/Services/Config/LanguageManager.swift): `AzathothsWhisper/Services/Config/LanguageManager.swift`

### Other components

- **User**
- **Music.app**
- **Genius API**
- **DarkLyrics**

## Connections

- User → App interface: uses (evidence: `AzathothsWhisper/Features/Shell/RootView.swift`)
- App interface → App coordinator: binds state (evidence: `AzathothsWhisper/Features/Shell/RootView.swift`)
- App interface → Batch screen: shows (evidence: `AzathothsWhisper/Features/Shell/RootView.swift`)
- App interface → Lyrics screen: shows (evidence: `AzathothsWhisper/Features/Shell/RootView.swift`)
- App coordinator → Track monitor: starts and refreshes (evidence: `AzathothsWhisper/App/AppModel.swift`)
- Track monitor → Apple Events client: reads playback
- Apple Events client → Music interface: implements (evidence: `AzathothsWhisper/Services/Music/MusicAppleEventsClient.swift`)
- Apple Events client → Music.app: sends Apple Events (evidence: `AzathothsWhisper/Services/Music/MusicAppleEventsClient.swift`)
- App coordinator → Lyrics editor: creates (evidence: `AzathothsWhisper/App/AppModel.swift`)
- App coordinator → Batch import: creates (evidence: `AzathothsWhisper/App/AppModel.swift`)
- App coordinator → Queue lyrics: creates and starts (evidence: `AzathothsWhisper/App/AppModel.swift`)
- App coordinator → Settings state: creates (evidence: `AzathothsWhisper/App/AppModel.swift`)
- Lyrics editor → Lyrics routing: fetches lyrics (evidence: `AzathothsWhisper/Features/Editor/EditorViewModel.swift`)
- Batch import → Lyrics routing: fetches missing lyrics (evidence: `AzathothsWhisper/Features/Batch/BatchViewModel.swift`)
- Lyrics editor → Music interface: reads and writes lyrics (evidence: `AzathothsWhisper/Features/Editor/EditorViewModel.swift`)
- Batch import → Music interface: loads and imports tracks (evidence: `AzathothsWhisper/Features/Batch/BatchViewModel.swift`)
- Lyrics routing → Genius source: queries first (evidence: `AzathothsWhisper/Services/Lyrics/LyricsService.swift`)
- Lyrics routing → DarkLyrics source: batch fallback (evidence: `AzathothsWhisper/Services/Lyrics/LyricsService.swift`)
- Genius source → HTTP client: uses HTTP
- DarkLyrics source → HTTP client: uses HTTP
- Genius source → Genius API: queries
- DarkLyrics source → DarkLyrics: queries
- Queue lyrics → Music interface: reads queue and playback
- Queue lyrics → Deck snapshot: builds deck (evidence: `AzathothsWhisper/Features/LyricsFlow/LyricsFlowModel.swift`)
- Deck snapshot → Queue session: uses queue session (evidence: `AzathothsWhisper/Features/LyricsFlow/QueueSession.swift`)
- Cover Flow state → Queue lyrics: gets deck state (evidence: `AzathothsWhisper/Features/CoverFlow/CoverFlowViewModel.swift`)
- App coordinator → Cover Flow state: creates (evidence: `AzathothsWhisper/App/AppModel.swift`)
- Cover Flow state → Artwork service: loads and prefetches (evidence: `AzathothsWhisper/Features/CoverFlow/CoverFlowViewModel.swift`)
- Artwork service → Music interface: fetches artwork (evidence: `AzathothsWhisper/Services/Artwork/ArtworkService.swift`)
- Artwork service → Memory cache: checks cache (evidence: `AzathothsWhisper/Services/Artwork/ArtworkService.swift`)
- Artwork service → Disk cache: loads and stores (evidence: `AzathothsWhisper/Services/Artwork/ArtworkService.swift`)
- Settings state → Configuration: reads and saves
- Settings state → Language manager: manages language
- App coordinator → Configuration: configures services (evidence: `AzathothsWhisper/App/AppModel.swift`)
- Settings state → App interface: presents settings (evidence: `AzathothsWhisper/Features/Shell/RootView.swift`)
