# pixelplayerhq/pixelplayer architecture

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

- Interactive diagram: https://gitdiagram.com/pixelplayerhq/pixelplayer
- Repository: https://github.com/pixelplayerhq/pixelplayer

## Overview

1. **Repository shape**
   - This is an Android music player split into three product modules: `app` (phone/tablet main app), `wear` (Wear OS companion), and `baselineprofile` (performance profiling/benchmark support).
   - A small `shared` module contains cross-device message/data contracts used by phone and watch.

2. **Top-level runtime**
   - The main runtime is the `app` module, built in Kotlin with Jetpack Compose, Material 3, Hilt, Room, WorkManager, Retrofit/OkHttp, Coil, and Media3 ExoPlayer.
   - The phone app is the system of record: it owns library data, playback state, preferences, backup/restore, and sync jobs.

3. **Presentation layer**
   - UI lives under `presentation/` and is organized by screens, reusable components, and ViewModels/state holders.
   - Navigation is centralized in `presentation/navigation`, while screen-specific UI flows cover library browsing, player, search, playlists, settings, stats, lyrics, AI, casting, and cloud-service dashboards.
   - The Compose UI is state-driven: screens observe ViewModels, and ViewModels adapt repository/service state into UI-ready models.

4. **Core data flow**
   - The standard flow is: UI → ViewModel/state holder → repository/service → local database/network/device APIs.
   - Domain models in `data/model` define the app’s shared concepts such as songs, albums, artists, playlists, queues, transitions, lyrics, and player state.

5. **Local persistence and indexing**
   - Room is the primary local persistence layer (`data/database`) with many entities and DAOs for songs, playlists, favorites, search history, engagement stats, lyrics, AI cache/usage, transitions, album art themes, and several cloud-provider caches.
   - Schema migration history is committed under `app/schemas`, which indicates database evolution is important to the app’s stability.
   - Preferences are stored separately in DataStore-backed repositories under `data/preferences`.

6. **Playback and media services**
   - `data/service/MusicService.kt` is the central background playback engine and likely the hub for media session, notification, queue control, and audio routing.
   - Playback is extended by specialized components for cast, local-only notifications, wake/sleep timer handling, widgets, media button handling, replay gain, hi-res/downmix processing, and dual-player/transition logic.
   - The player pipeline is therefore not just “play a file”; it is a service-centric media system with audio processing, queue management, and device-aware output routing.

7. **Library ingestion and media access**
   - The library is built from local device media via repository and paging layers (`MediaStoreSongRepository`, `MediaStorePagingSource`, `MediaStoreObserver`), plus filesystem/folder scanning helpers.
   - There is support for metadata reading/editing and playlist file handling (`AudioMetadataReader`, `SongMetadataEditor`, `M3uManager`), which means the app can both consume and modify local media metadata.
   - This layer feeds the UI library views and also powers search, playlists, and statistics.

8. **Cloud and external service integrations**
   - The app integrates with several external music sources and services: Deezer (artist images), LRCLIB (lyrics), GitHub services (announcements/contributors), Google Drive, Jellyfin, Navidrome, Netease, QQ Music, and Telegram.
   - These integrations are split into repositories, API services, stream proxies, security/encryption utilities, and provider-specific models.
   - Architecturally, these are pluggable remote sources that map remote catalogs/authentication into the app’s local domain and playback pipeline.

9. **AI subsystem**
   - AI features are isolated under `data/ai` and include orchestration, prompt building, metadata generation, playlist generation, notifications, and user profile digests.
   - Multiple AI providers are supported through a provider abstraction (`Gemini`, `OpenAI`, `Groq`, `Mistral`, `DeepSeek`, etc.), with client factory/support code handling provider-specific differences.
   - The AI layer feeds features like Daily Mix and AI-generated playlists, and it tracks usage/cache data in the database.

10. **Backup and restore**
   - Backup is a dedicated subsystem with manifest/model/format/validation/restore modules.
   - It is modularized by content areas such as favorites, playlists, lyrics, settings, playback history, transitions, equalizer, AI usage, and more.
   - This means backup/restore is not a simple export; it is a structured, validated, multi-section data migration pathway.

11. **Background synchronization and jobs**
   - WorkManager drives sync and maintenance tasks in `data/worker`, including general sync, Navidrome sync, and AI-related work.
   - These workers bridge remote service state into local storage and keep media/library metadata current outside the foreground UI.
   - The app also includes diagnostics and performance monitoring, showing that background behavior and startup performance are first-class concerns.

12. **Device ecosystem: widgets, cast, auto, wear**
   - The app exposes home-screen widgets via Glance, plus a `ContentProvider` for shared artwork and a set of widget update/broadcast components.
   - Casting and remote playback are handled inside the app through cast-specific services and HTTP/media proxy infrastructure.
   - Wear OS is a separate app module with its own database, repositories, playback service, and UI; it communicates with the phone through the `shared` message contracts and transfer/state repositories.
   - Android Auto support is present in the codebase structure, but the main architectural pattern is still “phone as controller + service host, wear as companion, widgets as lightweight views.”

13. **Cross-cutting concerns**
   - Dependency injection is centralized in `di/`, which wires repositories, services, and feature modules together.
   - The project also includes release/debug build separation, localization, baseline profiles, benchmark tests, and extensive unit/instrumentation tests across data, service, and presentation layers.
   - In an architecture diagram, the most important boundaries are: UI, domain/state, persistence, playback/service layer, external integrations, and companion-device communication.

Main entry points: [`app/src/main/java/com/theveloper/pixelplay/data/repository/MusicRepository.kt`](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/repository/MusicRepository.kt) (Repositories), [`app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt`](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt) (Room database), [`wear/src/main/java/com/theveloper/pixelplay/data/WearStateRepository.kt`](https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/data/WearStateRepository.kt) (Wear data), [`app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt`](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt) (Music service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Phone app"]
  node_app_main["Main app<br/>phone runtime<br/>[MainActivity.kt]"]
  node_app_nav["Navigation<br/>compose routing<br/>[AppNavigation.kt]"]
  node_app_ui["Screens<br/>compose UI<br/>[HomeScreen.kt]"]
  node_app_vm["ViewModels<br/>ui state<br/>[MainViewModel.kt]"]
  node_app_domain["Domain models<br/>shared concepts<br/>[LibraryModels.kt]"]
  node_app_repo["Repositories<br/>data access<br/>[MusicRepository.kt]"]
  node_app_db[("Room database<br/>local persistence")]
  node_app_prefs["Preferences<br/>datastore prefs"]
  node_app_service["Music service<br/>playback engine<br/>[MusicService.kt]"]
  node_app_player["Player pipeline<br/>audio processing"]
  node_app_integrations["Remote services<br/>cloud integrations"]
  node_app_ai["AI subsystem<br/>ai orchestration<br/>[AiOrchestrator.kt]"]
  node_app_backup["Backup system<br/>backup/restore<br/>[BackupManager.kt]"]
  node_app_sync["Workers<br/>background jobs<br/>[SyncManager.kt]"]
  node_app_device["Device features<br/>ecosystem support"]
end

subgraph group_wear["Wear OS app"]
  node_wear_main["Wear app<br/>watch runtime<br/>[WearApp.kt]"]
  node_wear_data["Wear data<br/>watch state/data"]
  node_wear_db[("Wear DB<br/>local watch db")]
  node_wear_ui["Wear UI<br/>watch compose UI<br/>[WearNavigation.kt]"]
end

subgraph group_shared["Shared contracts"]
  node_shared_contracts["Shared contracts<br/>cross-device models<br/>[WearIntents.kt]"]
end

subgraph group_baseline["Baseline profile"]
  node_baseline_profiles["Profiles<br/>benchmark tooling"]
end

node_app_main -->|"hosts"| node_app_nav
node_app_nav -->|"routes to"| node_app_ui
node_app_ui -->|"observes"| node_app_vm
node_app_vm -->|"requests"| node_app_repo
node_app_repo -->|"reads/writes"| node_app_db
node_app_repo -->|"uses"| node_app_prefs
node_app_repo -->|"maps to"| node_app_domain
node_app_repo -->|"drives"| node_app_service
node_app_service -->|"contains"| node_app_player
node_app_service -->|"publishes"| node_app_device
node_app_integrations -->|"syncs"| node_app_db
node_app_integrations -->|"feeds"| node_app_repo
node_app_ai -->|"caches"| node_app_db
node_app_ai -->|"produces"| node_app_repo
node_app_backup -->|"exports/imports"| node_app_db
node_app_backup -->|"exports/imports"| node_app_prefs
node_app_sync -->|"updates"| node_app_db
node_app_sync -->|"calls"| node_app_integrations
node_app_device -->|"uses"| node_shared_contracts
node_wear_main -->|"hosts"| node_wear_ui
node_wear_ui -->|"observes"| node_wear_data
node_wear_data -->|"reads/writes"| node_wear_db
node_wear_data -->|"syncs"| node_shared_contracts
node_wear_data -->|"communicates with"| node_app_device
node_baseline_profiles -->|"optimizes"| node_app_main

click node_app_main "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/MainActivity.kt"
click node_app_nav "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/presentation/navigation/AppNavigation.kt"
click node_app_ui "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/presentation/screens/HomeScreen.kt"
click node_app_vm "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel/MainViewModel.kt"
click node_app_domain "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/model/LibraryModels.kt"
click node_app_repo "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/repository/MusicRepository.kt"
click node_app_db "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt"
click node_app_prefs "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/preferences/UserPreferencesRepository.kt"
click node_app_service "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt"
click node_app_player "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/player/DualPlayerEngine.kt"
click node_app_integrations "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/network/lyrics/LrcLibApiService.kt"
click node_app_ai "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/ai/AiOrchestrator.kt"
click node_app_backup "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/backup/BackupManager.kt"
click node_app_sync "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/worker/SyncManager.kt"
click node_app_device "https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/wear/WearPhoneTransferSender.kt"
click node_wear_main "https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/WearApp.kt"
click node_wear_data "https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/data/WearStateRepository.kt"
click node_wear_db "https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/data/local/WearMusicDatabase.kt"
click node_wear_ui "https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/presentation/WearNavigation.kt"
click node_shared_contracts "https://github.com/pixelplayerhq/pixelplayer/blob/master/shared/src/main/java/com/theveloper/pixelplay/shared/WearIntents.kt"
click node_baseline_profiles "https://github.com/pixelplayerhq/pixelplayer/blob/master/baselineprofile/src/main/java/com/theveloper/pixelplay/baselineprofile/BaselineProfileGenerator.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_app_main,node_app_nav,node_app_ui,node_app_vm,node_app_domain,node_app_repo,node_app_db,node_app_prefs,node_app_service,node_app_player,node_app_integrations,node_app_ai,node_app_backup,node_app_sync,node_app_device toneBlue
class node_wear_main,node_wear_data,node_wear_db,node_wear_ui toneAmber
class node_shared_contracts toneMint
class node_baseline_profiles toneRose
```

## Components

### Phone app

Main Android runtime and system of record.

- [Main app](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/MainActivity.kt): phone runtime · Compose-based Android app host and entry points. · `app/src/main/java/com/theveloper/pixelplay/MainActivity.kt`
- [Navigation](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/presentation/navigation/AppNavigation.kt): compose routing · Central route and screen navigation coordination. · `app/src/main/java/com/theveloper/pixelplay/presentation/navigation/AppNavigation.kt`
- [Screens](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/presentation/screens/HomeScreen.kt): compose UI · Screen flows, reusable components, and feature surfaces. · `app/src/main/java/com/theveloper/pixelplay/presentation/screens/HomeScreen.kt`
- [ViewModels](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel/MainViewModel.kt): ui state · State holders that adapt repositories and services for UI. · `app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel/MainViewModel.kt`
- [Domain models](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/model/LibraryModels.kt): shared concepts · Core music, playback, search, lyrics, and queue models. · `app/src/main/java/com/theveloper/pixelplay/data/model/LibraryModels.kt`
- [Repositories](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/repository/MusicRepository.kt): data access · Library, lyrics, playlists, transitions, and media-store access. · `app/src/main/java/com/theveloper/pixelplay/data/repository/MusicRepository.kt`
- [Room database](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt): local persistence · Primary database for songs, playlists, stats, caches, and provider data. · `app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt`
- [Preferences](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/preferences/UserPreferencesRepository.kt): datastore prefs · User, theme, playlist, equalizer, and AI preference repositories. · `app/src/main/java/com/theveloper/pixelplay/data/preferences/UserPreferencesRepository.kt`
- [Music service](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt): playback engine · Foreground playback, media session, notification, queue, and routing hub. · `app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt`
- [Player pipeline](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/player/DualPlayerEngine.kt): audio processing · Dual player, cast playback, replay gain, downmix, and transition logic. · `app/src/main/java/com/theveloper/pixelplay/data/service/player/DualPlayerEngine.kt`
- [Remote services](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/network/lyrics/LrcLibApiService.kt): cloud integrations · External catalogs and APIs: Deezer, lyrics, GDrive, Jellyfin, Navidrome, Netease, QQ Music, Telegram, GitHub. · `app/src/main/java/com/theveloper/pixelplay/data/network/lyrics/LrcLibApiService.kt`
- [AI subsystem](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/ai/AiOrchestrator.kt): ai orchestration · Prompting, metadata/playlist generation, provider abstraction, notifications, and usage cache. · `app/src/main/java/com/theveloper/pixelplay/data/ai/AiOrchestrator.kt`
- [Backup system](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/backup/BackupManager.kt): backup/restore · Structured manifest, validation, module handlers, and restore execution. · `app/src/main/java/com/theveloper/pixelplay/data/backup/BackupManager.kt`
- [Workers](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/worker/SyncManager.kt): background jobs · WorkManager sync, maintenance, and AI work that updates local state. · `app/src/main/java/com/theveloper/pixelplay/data/worker/SyncManager.kt`
- [Device features](https://github.com/pixelplayerhq/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/wear/WearPhoneTransferSender.kt): ecosystem support · Widgets, shared artwork provider, cast, auto, wear transfer, and media buttons. · `app/src/main/java/com/theveloper/pixelplay/data/service/wear/WearPhoneTransferSender.kt`

### Wear OS app

Companion watch runtime and local player surface.

- [Wear app](https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/WearApp.kt): watch runtime · Wear OS companion application entry point and UI host. · `wear/src/main/java/com/theveloper/pixelplay/WearApp.kt`
- [Wear data](https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/data/WearStateRepository.kt): watch state/data · Watch repositories, local player, transfer, volume, and library state. · `wear/src/main/java/com/theveloper/pixelplay/data/WearStateRepository.kt`
- [Wear DB](https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/data/local/WearMusicDatabase.kt): local watch db · Wear-side Room database for cached songs and playback context. · `wear/src/main/java/com/theveloper/pixelplay/data/local/WearMusicDatabase.kt`
- [Wear UI](https://github.com/pixelplayerhq/pixelplayer/blob/master/wear/src/main/java/com/theveloper/pixelplay/presentation/WearNavigation.kt): watch compose UI · Watch navigation, screens, and compact playback controls. · `wear/src/main/java/com/theveloper/pixelplay/presentation/WearNavigation.kt`

### Shared contracts

Cross-device message and state models.

- [Shared contracts](https://github.com/pixelplayerhq/pixelplayer/blob/master/shared/src/main/java/com/theveloper/pixelplay/shared/WearIntents.kt): cross-device models · Wear browse, playback, transfer, volume, and theme message schemas. · `shared/src/main/java/com/theveloper/pixelplay/shared/WearIntents.kt`

### Baseline profile

Performance profiling and startup benchmarks.

- [Profiles](https://github.com/pixelplayerhq/pixelplayer/blob/master/baselineprofile/src/main/java/com/theveloper/pixelplay/baselineprofile/BaselineProfileGenerator.kt): benchmark tooling · Baseline profile generation and startup/player sheet benchmarks. · `baselineprofile/src/main/java/com/theveloper/pixelplay/baselineprofile/BaselineProfileGenerator.kt`

## Connections

- Main app → Navigation: hosts · Main activity launches the centralized navigation graph.
- Navigation → Screens: routes to · Navigation resolves screens and feature flows.
- Screens → ViewModels: observes · Compose screens render ViewModel/state-holder output.
- ViewModels → Repositories: requests · UI state is assembled from repositories and services.
- Repositories → Room database: reads/writes · Repositories persist and query local data through Room.
- Repositories → Preferences: uses · Repositories read and write user and feature preferences.
- Repositories → Domain models: maps to · Repository results are converted into app domain models.
- Repositories → Music service: drives · Playback-related repositories and controllers feed the music service.
- Music service → Player pipeline: contains · The service coordinates playback engines and audio processing.
- Music service → Device features: publishes · Service state powers widgets, buttons, cast, auto, and wear sync.
- Remote services → Room database: syncs · Remote catalogs and provider caches are stored locally.
- Remote services → Repositories: feeds · Service-specific repositories expose remote data to the app.
- AI subsystem → Room database: caches · AI usage and generated content are tracked in local storage.
- AI subsystem → Repositories: produces · AI-generated playlists and metadata flow into app features.
- Backup system → Room database: exports/imports · Backup modules serialize and restore app data sections.
- Backup system → Preferences: exports/imports · Settings and preference state participate in backup/restore.
- Workers → Room database: updates · Workers reconcile remote and local state in the database.
- Workers → Remote services: calls · Background jobs fetch from cloud services and AI providers.
- Device features → Shared contracts: uses · Phone features exchange structured payloads with wear.
- Wear app → Wear UI: hosts · Wear activity launches the watch navigation and screens.
- Wear UI → Wear data: observes · Wear screens render repository-backed watch state.
- Wear data → Wear DB: reads/writes · Watch repositories persist cached music and player state.
- Wear data → Shared contracts: syncs · Wear data exchange is defined by shared cross-device models.
- Wear data → Device features: communicates with · Watch state and commands travel through phone-side transfer services.
- Profiles → Main app: optimizes · Generated profiles target app startup and player interactions.