# maxcodl/paperplay architecture

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

- Interactive diagram: https://gitdiagram.com/maxcodl/paperplay
- Repository: https://github.com/maxcodl/paperplay

## Overview

PaperPlay is a cross-platform music player whose library is sourced from the user’s Telegram chats and bots. Users configure access, scan chats and local folders, then browse and play the resulting library; playback is coordinated by a shared controller and platform-specific engines. Other major branches include metadata and lyrics, recommendations, library management, device sync and network play, backup, and updates. The README documents these capabilities; sampled code confirms selected startup, playback, service, and cover-fetch relationships, so unsampled connections are omitted rather than inferred.

Main entry points: [`ui/src/commonMain/kotlin/io/max/paperplay/ui/App.kt`](https://github.com/maxcodl/paperplay/blob/main/ui/src/commonMain/kotlin/io/max/paperplay/ui/App.kt) (Compose UI), [`core/src/commonMain/kotlin/io/max/paperplay/core/app/LibraryRepository.kt`](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/LibraryRepository.kt) (Library repository), [`core/src/commonMain/kotlin/io/max/paperplay/core/app/AppServices.kt`](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/AppServices.kt) (App services), [`core/src/commonMain/kotlin/io/max/paperplay/core/app/Scanner.kt`](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/Scanner.kt) (Chat scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and UI"]
  node_ui["Compose UI<br/>[App.kt]"]
  node_backend["Core backend<br/>[CoreBackend.kt]"]
  node_services["App services<br/>[AppServices.kt]"]
end

subgraph group_library["Library and discovery"]
  node_library_repo["Library repository"]
  node_library_domain[("Library model<br/>[LibraryRepo.kt]")]
  node_telegram["Telegram clients<br/>[TdClient.kt]"]
  node_scanner["Chat scanning<br/>[Scanner.kt]"]
  node_local_folders["Local folders<br/>[LocalFolders.kt]"]
  node_metadata["Metadata and lyrics<br/>[SongSearch.kt]"]
  node_cover["Cover service<br/>[CoverService.kt]"]
  node_filing["Topics and filing<br/>[Topics.kt]"]
  node_duplicates["Duplicate cleanup<br/>[Duplicates.kt]"]
end

subgraph group_playback["Playback"]
  node_playback_controller["Playback controller"]
  node_player_engine["Player engine<br/>[PlayerEngine.kt]"]
  node_android_player["Android player"]
  node_desktop_player["Desktop player<br/>[MpvPlayerEngine.kt]"]
  node_usb_audio["USB audio<br/>[UsbAudioManager.kt]"]
end

subgraph group_connected["Connected features"]
  node_recommendations["Mixes and discovery"]
  node_integrations["Music integrations"]
  node_device_sync["Device sync<br/>[LanSync.kt]"]
  node_netplay["Network play<br/>[NetplaySync.kt]"]
  node_backup["Backup and restore<br/>[BackupWriter.kt]"]
end

subgraph group_platform["Platform services"]
  node_database[("Library database<br/>[LibrarySchema.kt]")]
  node_android_app["Android host<br/>[MainActivity.kt]"]
  node_desktop_app["Desktop host<br/>[Main.kt]"]
  node_updates["Update service<br/>[UpdateService.kt]"]
end

node_user(("Listener"))

node_user -->|"uses"| node_ui
node_ui -->|"builds"| node_backend
node_backend -->|"creates"| node_services
node_services -.->|"provides"| node_library_repo
node_services -->|"configures"| node_telegram
node_user -->|"starts scans"| node_scanner
node_scanner -->|"reads chats"| node_telegram
node_scanner -.->|"indexes songs"| node_library_repo
node_user -->|"chooses folders"| node_local_folders
node_user -->|"browses library"| node_library_repo
node_library_repo -.->|"stores library"| node_library_domain
node_library_repo -.->|"persists data"| node_database
node_user -->|"searches songs"| node_metadata
node_user -->|"views covers"| node_cover
node_cover -->|"fetches thumbnails"| node_telegram
node_user -->|"manages topics"| node_filing
node_user -->|"cleans duplicates"| node_duplicates
node_ui -.->|"controls playback"| node_playback_controller
node_playback_controller -->|"commands"| node_player_engine
node_player_engine -.->|"implemented by"| node_android_player
node_player_engine -.->|"implemented by"| node_desktop_player
node_user -->|"enables bit-perfect"| node_usb_audio
node_user -->|"explores mixes"| node_recommendations
node_user -->|"imports and enriches"| node_integrations
node_user -->|"syncs devices"| node_device_sync
node_user -->|"joins session"| node_netplay
node_user -->|"backs up library"| node_backup
node_android_app -.->|"hosts"| node_ui
node_desktop_app -->|"hosts"| node_ui
node_user -->|"checks updates"| node_updates

click node_ui "https://github.com/maxcodl/paperplay/blob/main/ui/src/commonMain/kotlin/io/max/paperplay/ui/App.kt"
click node_backend "https://github.com/maxcodl/paperplay/blob/main/ui/src/commonMain/kotlin/io/max/paperplay/ui/app/CoreBackend.kt"
click node_services "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/AppServices.kt"
click node_library_repo "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/LibraryRepository.kt"
click node_library_domain "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/library/LibraryRepo.kt"
click node_telegram "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/telegram/TdClient.kt"
click node_scanner "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/Scanner.kt"
click node_local_folders "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/LocalFolders.kt"
click node_metadata "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/metadata/SongSearch.kt"
click node_cover "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/CoverService.kt"
click node_filing "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/filing/Topics.kt"
click node_duplicates "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/dupes/Duplicates.kt"
click node_playback_controller "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/PlaybackController.kt"
click node_player_engine "https://github.com/maxcodl/paperplay/blob/main/player/src/commonMain/kotlin/io/max/paperplay/player/PlayerEngine.kt"
click node_android_player "https://github.com/maxcodl/paperplay/blob/main/player/src/androidMain/kotlin/io/max/paperplay/player/AndroidPlayerEngine.kt"
click node_desktop_player "https://github.com/maxcodl/paperplay/blob/main/player/src/jvmMain/kotlin/io/max/paperplay/player/MpvPlayerEngine.kt"
click node_usb_audio "https://github.com/maxcodl/paperplay/blob/main/player/src/androidMain/kotlin/io/max/paperplay/player/usb/UsbAudioManager.kt"
click node_recommendations "https://github.com/maxcodl/paperplay/tree/main/core/src/commonMain/kotlin/io/max/paperplay/core/recs"
click node_integrations "https://github.com/maxcodl/paperplay/tree/main/core/src/commonMain/kotlin/io/max/paperplay/core/integrations"
click node_device_sync "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/sync/LanSync.kt"
click node_netplay "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/sync/netplay/NetplaySync.kt"
click node_backup "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/backup/BackupWriter.kt"
click node_database "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/db/LibrarySchema.kt"
click node_android_app "https://github.com/maxcodl/paperplay/blob/main/androidApp/src/main/kotlin/io/max/paperplay/compose/MainActivity.kt"
click node_desktop_app "https://github.com/maxcodl/paperplay/blob/main/desktopApp/src/jvmMain/kotlin/io/max/paperplay/desktop/Main.kt"
click node_updates "https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/update/UpdateService.kt"

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_ui,node_backend,node_services toneBlue
class node_library_repo,node_library_domain,node_telegram,node_scanner,node_local_folders,node_metadata,node_cover,node_filing,node_duplicates toneAmber
class node_playback_controller,node_player_engine,node_android_player,node_desktop_player,node_usb_audio toneMint
class node_recommendations,node_integrations,node_device_sync,node_netplay,node_backup toneRose
class node_database,node_android_app,node_desktop_app,node_updates,node_user toneIndigo
```

## Components

### App and UI

- [Compose UI](https://github.com/maxcodl/paperplay/blob/main/ui/src/commonMain/kotlin/io/max/paperplay/ui/App.kt): `ui/src/commonMain/kotlin/io/max/paperplay/ui/App.kt`
- [Core backend](https://github.com/maxcodl/paperplay/blob/main/ui/src/commonMain/kotlin/io/max/paperplay/ui/app/CoreBackend.kt): `ui/src/commonMain/kotlin/io/max/paperplay/ui/app/CoreBackend.kt`
- [App services](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/AppServices.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/app/AppServices.kt`

### Library and discovery

- [Library repository](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/LibraryRepository.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/app/LibraryRepository.kt`
- [Library model](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/library/LibraryRepo.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/library/LibraryRepo.kt`
- [Telegram clients](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/telegram/TdClient.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/telegram/TdClient.kt`
- [Chat scanning](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/Scanner.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/app/Scanner.kt`
- [Local folders](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/LocalFolders.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/app/LocalFolders.kt`
- [Metadata and lyrics](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/metadata/SongSearch.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/metadata/SongSearch.kt`
- [Cover service](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/CoverService.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/app/CoverService.kt`
- [Topics and filing](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/filing/Topics.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/filing/Topics.kt`
- [Duplicate cleanup](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/dupes/Duplicates.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/dupes/Duplicates.kt`

### Playback

- [Playback controller](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/app/PlaybackController.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/app/PlaybackController.kt`
- [Player engine](https://github.com/maxcodl/paperplay/blob/main/player/src/commonMain/kotlin/io/max/paperplay/player/PlayerEngine.kt): `player/src/commonMain/kotlin/io/max/paperplay/player/PlayerEngine.kt`
- [Android player](https://github.com/maxcodl/paperplay/blob/main/player/src/androidMain/kotlin/io/max/paperplay/player/AndroidPlayerEngine.kt): `player/src/androidMain/kotlin/io/max/paperplay/player/AndroidPlayerEngine.kt`
- [Desktop player](https://github.com/maxcodl/paperplay/blob/main/player/src/jvmMain/kotlin/io/max/paperplay/player/MpvPlayerEngine.kt): `player/src/jvmMain/kotlin/io/max/paperplay/player/MpvPlayerEngine.kt`
- [USB audio](https://github.com/maxcodl/paperplay/blob/main/player/src/androidMain/kotlin/io/max/paperplay/player/usb/UsbAudioManager.kt): `player/src/androidMain/kotlin/io/max/paperplay/player/usb/UsbAudioManager.kt`

### Connected features

- [Mixes and discovery](https://github.com/maxcodl/paperplay/tree/main/core/src/commonMain/kotlin/io/max/paperplay/core/recs): `core/src/commonMain/kotlin/io/max/paperplay/core/recs`
- [Music integrations](https://github.com/maxcodl/paperplay/tree/main/core/src/commonMain/kotlin/io/max/paperplay/core/integrations): `core/src/commonMain/kotlin/io/max/paperplay/core/integrations`
- [Device sync](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/sync/LanSync.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/sync/LanSync.kt`
- [Network play](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/sync/netplay/NetplaySync.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/sync/netplay/NetplaySync.kt`
- [Backup and restore](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/backup/BackupWriter.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/backup/BackupWriter.kt`

### Platform services

- [Library database](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/db/LibrarySchema.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/db/LibrarySchema.kt`
- [Android host](https://github.com/maxcodl/paperplay/blob/main/androidApp/src/main/kotlin/io/max/paperplay/compose/MainActivity.kt): `androidApp/src/main/kotlin/io/max/paperplay/compose/MainActivity.kt`
- [Desktop host](https://github.com/maxcodl/paperplay/blob/main/desktopApp/src/jvmMain/kotlin/io/max/paperplay/desktop/Main.kt): `desktopApp/src/jvmMain/kotlin/io/max/paperplay/desktop/Main.kt`
- [Update service](https://github.com/maxcodl/paperplay/blob/main/core/src/commonMain/kotlin/io/max/paperplay/core/update/UpdateService.kt): `core/src/commonMain/kotlin/io/max/paperplay/core/update/UpdateService.kt`

### Other components

- **Listener**

## Connections

- Listener → Compose UI: uses (evidence: `README.md`)
- Compose UI → Core backend: builds (evidence: `ui/src/commonMain/kotlin/io/max/paperplay/ui/App.kt`)
- Core backend → App services: creates (evidence: `ui/src/commonMain/kotlin/io/max/paperplay/ui/App.kt`)
- App services → Library repository: provides (evidence: `core/src/commonMain/kotlin/io/max/paperplay/core/app/AppServices.kt`)
- App services → Telegram clients: configures (evidence: `core/src/commonMain/kotlin/io/max/paperplay/core/app/AppServices.kt`)
- Listener → Chat scanning: starts scans (evidence: `README.md`)
- Chat scanning → Telegram clients: reads chats (evidence: `README.md`)
- Chat scanning → Library repository: indexes songs
- Listener → Local folders: chooses folders (evidence: `README.md`)
- Listener → Library repository: browses library (evidence: `README.md`)
- Library repository → Library model: stores library (evidence: `core/src/commonMain/kotlin/io/max/paperplay/core/app/LibraryRepository.kt`)
- Library repository → Library database: persists data
- Listener → Metadata and lyrics: searches songs (evidence: `README.md`)
- Listener → Cover service: views covers (evidence: `README.md`)
- Cover service → Telegram clients: fetches thumbnails (evidence: `core/src/commonMain/kotlin/io/max/paperplay/core/app/CoverService.kt`)
- Listener → Topics and filing: manages topics (evidence: `README.md`)
- Listener → Duplicate cleanup: cleans duplicates (evidence: `README.md`)
- Compose UI → Playback controller: controls playback
- Playback controller → Player engine: commands (evidence: `core/src/commonMain/kotlin/io/max/paperplay/core/app/PlaybackController.kt`)
- Player engine → Android player: implemented by (evidence: `player/src/androidMain/kotlin/io/max/paperplay/player/AndroidPlayerEngine.kt`)
- Player engine → Desktop player: implemented by (evidence: `player/src/jvmMain/kotlin/io/max/paperplay/player/MpvPlayerEngine.kt`)
- Listener → USB audio: enables bit-perfect (evidence: `README.md`)
- Listener → Mixes and discovery: explores mixes (evidence: `README.md`)
- Listener → Music integrations: imports and enriches (evidence: `README.md`)
- Listener → Device sync: syncs devices (evidence: `README.md`)
- Listener → Network play: joins session (evidence: `README.md`)
- Listener → Backup and restore: backs up library (evidence: `README.md`)
- Android host → Compose UI: hosts (evidence: `androidApp/src/main/kotlin/io/max/paperplay/compose/MainActivity.kt`)
- Desktop host → Compose UI: hosts (evidence: `desktopApp/src/jvmMain/kotlin/io/max/paperplay/desktop/Main.kt`)
- Listener → Update service: checks updates (evidence: `README.md`)
