# kushalpandya/petrichor architecture

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

## Overview

Petrichor is an offline macOS music player. Its main workflow is to add music folders, extract track metadata into a persistent library, browse or organize that library, then queue and play tracks. Separate product areas cover playlists, internet radio, lyrics, artist information, and macOS automation and playback controls. The graph reflects the documented capabilities and sampled manager/backend responsibilities; some subsystem links are omitted because their call sites were not included in the excerpts.

Main entry points: [`Managers/PlaybackManager.swift`](https://github.com/kushalpandya/petrichor/blob/main/Managers/PlaybackManager.swift) (Playback manager), [`Managers/Library/LibraryManager.swift`](https://github.com/kushalpandya/petrichor/blob/main/Managers/Library/LibraryManager.swift) (Library manager), [`Managers/Playlist/PlaylistManager.swift`](https://github.com/kushalpandya/petrichor/blob/main/Managers/Playlist/PlaylistManager.swift) (Playlist manager), [`Views/Main/ContentView.swift`](https://github.com/kushalpandya/petrichor/blob/main/Views/Main/ContentView.swift) (Main interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and Interface"]
  node_app["App lifecycle"]
  node_mainui["Main interface<br/>[ContentView.swift]"]
  node_libraryui["Library views<br/>[LibraryView.swift]"]
  node_folderui["Folder views<br/>[FoldersView.swift]"]
  node_playlistui["Playlist views"]
  node_radio_ui["Radio views"]
  node_playerui["Player controls<br/>[PlayerView.swift]"]
  node_mini["Mini player"]
end

subgraph group_library["Music Library"]
  node_librarymgr["Library manager"]
  node_metadata["Metadata engine"]
  node_models["Music entities<br/>[Track.swift]"]
  node_database[("Library database")]
  node_folderbuilder["Folder hierarchy"]
end

subgraph group_playback["Playback"]
  node_playbackmgr["Playback manager"]
  node_queue["Queue management<br/>[PMQueue.swift]"]
  node_engine["Playback engine"]
  node_backend["Audio backend"]
  node_remote["macOS controls"]
end

subgraph group_extras["Music Features"]
  node_playlists["Playlist manager"]
  node_playlistlogic["Playlist operations"]
  node_radio["Radio manager"]
  node_lyrics["Lyrics manager"]
  node_artistbio["Artist information"]
  node_automation["Automation commands"]
end

node_listener(("Listener"))
node_radio_service(("Radio directory"))
node_online(("Online music services"))
node_audio_output(("Audio output"))

node_listener -->|"uses"| node_mainui
node_app -->|"coordinates"| node_librarymgr
node_app -->|"coordinates"| node_playbackmgr
node_app -->|"coordinates"| node_playlists
node_mainui -->|"shows"| node_libraryui
node_mainui -->|"shows"| node_folderui
node_mainui -->|"shows"| node_playlistui
node_mainui -->|"shows"| node_radio_ui
node_libraryui -->|"requests library"| node_librarymgr
node_folderui -->|"requests folders"| node_librarymgr
node_librarymgr -->|"extracts tags"| node_metadata
node_librarymgr -->|"reads and writes"| node_database
node_metadata -->|"produces metadata"| node_models
node_librarymgr -->|"builds hierarchy"| node_folderbuilder
node_playlistui -->|"manages playlists"| node_playlists
node_playlists -->|"delegates operations"| node_playlistlogic
node_playlists -->|"loads and saves"| node_database
node_playlists -->|"controls playback"| node_playbackmgr
node_radio_ui -->|"manages stations"| node_radio
node_radio -->|"loads and saves"| node_database
node_radio -.->|"fetches directory"| node_radio_service
node_lyrics -.->|"fetches lyrics"| node_online
node_artistbio -.->|"fetches biographies"| node_online
node_artistbio -->|"stores information"| node_database
node_automation -->|"queries and controls"| node_playbackmgr
node_automation -->|"manages playlists"| node_playlists
node_automation -->|"queries library"| node_librarymgr
node_playerui -->|"controls playback"| node_playbackmgr
node_mini -->|"displays controls"| node_playbackmgr
node_remote -->|"sends commands"| node_playbackmgr
node_playbackmgr -->|"coordinates playback"| node_engine
node_playbackmgr -->|"manages queue"| node_queue
node_engine -->|"forwards audio operations"| node_backend
node_backend -->|"renders audio"| node_audio_output

click node_app "https://github.com/kushalpandya/petrichor/blob/main/Application/AppCoordinator.swift"
click node_mainui "https://github.com/kushalpandya/petrichor/blob/main/Views/Main/ContentView.swift"
click node_libraryui "https://github.com/kushalpandya/petrichor/blob/main/Views/Library/LibraryView.swift"
click node_folderui "https://github.com/kushalpandya/petrichor/blob/main/Views/Folders/FoldersView.swift"
click node_playlistui "https://github.com/kushalpandya/petrichor/blob/main/Views/Playlists/PlaylistsView.swift"
click node_radio_ui "https://github.com/kushalpandya/petrichor/blob/main/Views/Radio/InternetRadioView.swift"
click node_librarymgr "https://github.com/kushalpandya/petrichor/blob/main/Managers/Library/LibraryManager.swift"
click node_metadata "https://github.com/kushalpandya/petrichor/blob/main/Core/Metadata/MetadataEngine.swift"
click node_models "https://github.com/kushalpandya/petrichor/blob/main/Models/Core/Track.swift"
click node_database "https://github.com/kushalpandya/petrichor/blob/main/Managers/Database/DatabaseManager.swift"
click node_folderbuilder "https://github.com/kushalpandya/petrichor/blob/main/Managers/FolderHierarchyBuilder.swift"
click node_playlists "https://github.com/kushalpandya/petrichor/blob/main/Managers/Playlist/PlaylistManager.swift"
click node_playlistlogic "https://github.com/kushalpandya/petrichor/blob/main/Managers/Playlist/PMRegularPlaylists.swift"
click node_radio "https://github.com/kushalpandya/petrichor/blob/main/Managers/InternetRadioManager.swift"
click node_lyrics "https://github.com/kushalpandya/petrichor/blob/main/Managers/LyricsManager.swift"
click node_artistbio "https://github.com/kushalpandya/petrichor/blob/main/Managers/ArtistBioManager.swift"
click node_automation "https://github.com/kushalpandya/petrichor/blob/main/Managers/Automation/AutomationManager.swift"
click node_playbackmgr "https://github.com/kushalpandya/petrichor/blob/main/Managers/PlaybackManager.swift"
click node_queue "https://github.com/kushalpandya/petrichor/blob/main/Managers/Playlist/PMQueue.swift"
click node_engine "https://github.com/kushalpandya/petrichor/blob/main/Core/Playback/PlaybackEngine.swift"
click node_backend "https://github.com/kushalpandya/petrichor/blob/main/Core/Playback/CrescendoPlaybackBackend.swift"
click node_playerui "https://github.com/kushalpandya/petrichor/blob/main/Views/Main/PlayerView.swift"
click node_mini "https://github.com/kushalpandya/petrichor/blob/main/Views/MiniPlayer/MiniPlayerWindowManager.swift"
click node_remote "https://github.com/kushalpandya/petrichor/blob/main/Managers/RemoteCommandManager.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_mainui,node_libraryui,node_folderui,node_playlistui,node_radio_ui,node_playerui,node_mini toneBlue
class node_librarymgr,node_metadata,node_models,node_database,node_folderbuilder toneAmber
class node_playbackmgr,node_queue,node_engine,node_backend,node_remote toneMint
class node_playlists,node_playlistlogic,node_radio,node_lyrics,node_artistbio,node_automation toneRose
class node_listener,node_radio_service,node_online,node_audio_output toneIndigo
```

## Components

### App and Interface

- [App lifecycle](https://github.com/kushalpandya/petrichor/blob/main/Application/AppCoordinator.swift): `Application/AppCoordinator.swift`
- [Main interface](https://github.com/kushalpandya/petrichor/blob/main/Views/Main/ContentView.swift): `Views/Main/ContentView.swift`
- [Library views](https://github.com/kushalpandya/petrichor/blob/main/Views/Library/LibraryView.swift): `Views/Library/LibraryView.swift`
- [Folder views](https://github.com/kushalpandya/petrichor/blob/main/Views/Folders/FoldersView.swift): `Views/Folders/FoldersView.swift`
- [Playlist views](https://github.com/kushalpandya/petrichor/blob/main/Views/Playlists/PlaylistsView.swift): `Views/Playlists/PlaylistsView.swift`
- [Radio views](https://github.com/kushalpandya/petrichor/blob/main/Views/Radio/InternetRadioView.swift): `Views/Radio/InternetRadioView.swift`
- [Player controls](https://github.com/kushalpandya/petrichor/blob/main/Views/Main/PlayerView.swift): `Views/Main/PlayerView.swift`
- [Mini player](https://github.com/kushalpandya/petrichor/blob/main/Views/MiniPlayer/MiniPlayerWindowManager.swift): `Views/MiniPlayer/MiniPlayerWindowManager.swift`

### Music Library

- [Library manager](https://github.com/kushalpandya/petrichor/blob/main/Managers/Library/LibraryManager.swift): `Managers/Library/LibraryManager.swift`
- [Metadata engine](https://github.com/kushalpandya/petrichor/blob/main/Core/Metadata/MetadataEngine.swift): `Core/Metadata/MetadataEngine.swift`
- [Music entities](https://github.com/kushalpandya/petrichor/blob/main/Models/Core/Track.swift): `Models/Core/Track.swift`
- [Library database](https://github.com/kushalpandya/petrichor/blob/main/Managers/Database/DatabaseManager.swift): `Managers/Database/DatabaseManager.swift`
- [Folder hierarchy](https://github.com/kushalpandya/petrichor/blob/main/Managers/FolderHierarchyBuilder.swift): `Managers/FolderHierarchyBuilder.swift`

### Playback

- [Playback manager](https://github.com/kushalpandya/petrichor/blob/main/Managers/PlaybackManager.swift): `Managers/PlaybackManager.swift`
- [Queue management](https://github.com/kushalpandya/petrichor/blob/main/Managers/Playlist/PMQueue.swift): `Managers/Playlist/PMQueue.swift`
- [Playback engine](https://github.com/kushalpandya/petrichor/blob/main/Core/Playback/PlaybackEngine.swift): `Core/Playback/PlaybackEngine.swift`
- [Audio backend](https://github.com/kushalpandya/petrichor/blob/main/Core/Playback/CrescendoPlaybackBackend.swift): `Core/Playback/CrescendoPlaybackBackend.swift`
- [macOS controls](https://github.com/kushalpandya/petrichor/blob/main/Managers/RemoteCommandManager.swift): `Managers/RemoteCommandManager.swift`

### Music Features

- [Playlist manager](https://github.com/kushalpandya/petrichor/blob/main/Managers/Playlist/PlaylistManager.swift): `Managers/Playlist/PlaylistManager.swift`
- [Playlist operations](https://github.com/kushalpandya/petrichor/blob/main/Managers/Playlist/PMRegularPlaylists.swift): `Managers/Playlist/PMRegularPlaylists.swift`
- [Radio manager](https://github.com/kushalpandya/petrichor/blob/main/Managers/InternetRadioManager.swift): `Managers/InternetRadioManager.swift`
- [Lyrics manager](https://github.com/kushalpandya/petrichor/blob/main/Managers/LyricsManager.swift): `Managers/LyricsManager.swift`
- [Artist information](https://github.com/kushalpandya/petrichor/blob/main/Managers/ArtistBioManager.swift): `Managers/ArtistBioManager.swift`
- [Automation commands](https://github.com/kushalpandya/petrichor/blob/main/Managers/Automation/AutomationManager.swift): `Managers/Automation/AutomationManager.swift`

### Other components

- **Listener**
- **Radio directory**
- **Online music services**
- **Audio output**

## Connections

- Listener → Main interface: uses
- App lifecycle → Library manager: coordinates
- App lifecycle → Playback manager: coordinates
- App lifecycle → Playlist manager: coordinates
- Main interface → Library views: shows
- Main interface → Folder views: shows
- Main interface → Playlist views: shows
- Main interface → Radio views: shows
- Library views → Library manager: requests library
- Folder views → Library manager: requests folders
- Library manager → Metadata engine: extracts tags
- Library manager → Library database: reads and writes
- Metadata engine → Music entities: produces metadata
- Library manager → Folder hierarchy: builds hierarchy
- Playlist views → Playlist manager: manages playlists
- Playlist manager → Playlist operations: delegates operations
- Playlist manager → Library database: loads and saves
- Playlist manager → Playback manager: controls playback
- Radio views → Radio manager: manages stations
- Radio manager → Library database: loads and saves
- Radio manager → Radio directory: fetches directory
- Lyrics manager → Online music services: fetches lyrics
- Artist information → Online music services: fetches biographies
- Artist information → Library database: stores information
- Automation commands → Playback manager: queries and controls
- Automation commands → Playlist manager: manages playlists
- Automation commands → Library manager: queries library
- Player controls → Playback manager: controls playback
- Mini player → Playback manager: displays controls
- macOS controls → Playback manager: sends commands
- Playback manager → Playback engine: coordinates playback
- Playback manager → Queue management: manages queue
- Playback engine → Audio backend: forwards audio operations
- Audio backend → Audio output: renders audio