# cromaguy/rhythm architecture

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

- Interactive diagram: https://gitdiagram.com/cromaguy/rhythm
- Repository: https://github.com/cromaguy/rhythm

## Overview

1. **What this repository is**
   Rhythm is a single-module Android music player app written in Kotlin. Its architecture is centered on a long-lived playback service, a Compose-based UI, and two interchangeable music backends: local-library playback and streaming-service playback.

2. **Primary application boundary**
   The Android app lives under `app/`. `RhythmApplication` is the process-level entry point, while `MainActivity`, `ExternalPlaybackActivity`, `CrashActivity`, and `RhythmGuardTimeoutActivity` are the main UI/service-facing activities. The app is packaged with build variants for GitHub, F-Droid, and other distribution channels.

3. **Overall layer split**
   The codebase follows MVVM plus a clean-architecture style:
   - `core/` defines shared domain concepts and repository contracts.
   - `shared/` contains cross-cutting models, repositories, UI, and viewmodels.
   - `features/local/` and `features/streaming/` implement the two playback modes.
   - `infrastructure/` contains low-level playback, networking, widgets, workers, and audio processors.
   - `util/` and `utils/` hold app-wide helpers that don’t belong to a single feature.

4. **Domain and orchestration**
   The main domain abstractions are `PlayableItem`, `MediaItems`, `AppMode`, `MusicRepository`, and `SongUseCases`. These are the boundaries the UI and viewmodels depend on, so the rest of the app can switch between local and streaming behavior without rewriting the screens.

5. **Local music subsystem**
   `features/local/` owns the on-device library experience. It includes a Room database (`RhythmDatabase`) with song, artist, and join-table entities/DAOs, plus `MusicRepositoryImpl` to expose local library operations. Local presentation includes home/library screens, onboarding, playlist management, equalizer screens, and library metadata/notification managers.

6. **Streaming subsystem**
   `features/streaming/` mirrors the local stack but targets remote providers. It defines streaming domain models (`StreamingSong`, `StreamingAlbum`, `StreamingArtist`, `StreamingPlaylist`, etc.), provider clients (`JellyfinApiClient`, `SubsonicApiClient`), a streaming repository implementation, and a session repository. The streaming UI includes setup, integration, home/library, settings, and service-selection flows.

7. **Playback engine and media service**
   The heart of audio playback is `infrastructure/service/MediaPlaybackService` backed by `RhythmPlayerEngine`. Supporting components handle queue transitions, preload/caching, and playback state transfer. This service boundary is what the UI, widgets, notifications, and external playback activity all ultimately talk to.

8. **Audio processing chain**
   Audio enhancement is implemented in `infrastructure/audio/` and `infrastructure/service/player/replaygain/`. The app includes bass boost, spatialization, adaptive dynamic range compression, ReplayGain processing, and device/output handling. Utility classes like `AudioDeviceManager`, `AudioCapabilitiesMonitor`, `CodecMonitor`, and `AudioFormatDetector` influence playback behavior and the “high-res” style audio features described in the README.

9. **Network and metadata integrations**
   External metadata and content services live in `infrastructure/network/` and `features/streaming/data/provider/`. The app talks to Deezer, Spotify search, YouTube Music, iTunes Search, LRCLib, and a Rhythm lyrics backend, plus GitHub for release/update data. These services feed artwork, search results, lyrics, and update checks rather than core playback.

10. **State management and persistence**
   App state is split between persistent repositories and Compose viewmodels. Shared repositories such as `UserPreferencesRepository` and `PlaybackStatsRepository` store settings and listening history, while feature viewmodels (`MusicViewModel`, `StreamingMusicViewModel`, `AppModeViewModel`, `ThemeViewModel`, `AppUpdaterViewModel`) bridge repository data into UI state. Room handles the local library cache; preferences and stats handle user configuration and analytics-like insights on-device.

11. **UI structure and navigation**
   The UI is entirely Compose-based and organized by shared versus feature-specific screens. `shared/presentation/navigation` and the feature navigation files define the main app routes, while screens are split across player, settings, search, home, library, onboarding, and streaming-specific pages. The shared UI layer also contains reusable components, dialogs, bottom sheets, theme, and mini-player variants.

12. **Background work, widgets, and system integration**
   Background synchronization and maintenance are handled by WorkManager workers such as backup, update notifications, and pulse notifications. Home-screen widgets are supported through both legacy AppWidget and Glance-based implementations, with separate widget update/receiver/worker components. Additional system-facing pieces include crash reporting, ANR watchdogging, privacy-policy assets, and release/update automation in GitHub Actions and fastlane metadata.

13. **Build-time and distribution boundaries**
   The repository uses product flavors and resource overlays for different builds (`github`, `fdroid`, `debug`), which affect configuration, feature availability, and distribution packaging. Release metadata, screenshots, and changelogs live alongside the app sources, indicating an Android release pipeline rather than a server/client split.

14. **How data typically flows**
   User interaction starts in Compose screens, which call viewmodels. Viewmodels read from repositories/use cases, which delegate to either the local Room-backed repository or the streaming repository. Playback requests flow from UI to `MediaPlaybackService`/`RhythmPlayerEngine`; metadata, lyrics, and artwork may come from network providers; and side effects such as widgets, notifications, stats, and backups are updated asynchronously through workers and managers.

Main entry points: [`app/src/main/java/chromahub/rhythm/app/infrastructure/service/MediaPlaybackService.kt`](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/service/MediaPlaybackService.kt) (Player Engine), [`app/src/main/java/chromahub/rhythm/app/shared/presentation/viewmodel/MusicViewModel.kt`](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/presentation/viewmodel/MusicViewModel.kt) (Shared VM), [`app/src/main/java/chromahub/rhythm/app/features/streaming/data/repository/StreamingMusicRepositoryImpl.kt`](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/streaming/data/repository/StreamingMusicRepositoryImpl.kt) (Streaming Repo), [`app/src/main/java/chromahub/rhythm/app/core/domain/repository/MusicRepository.kt`](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/core/domain/repository/MusicRepository.kt) (Music Repo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_n1(("RhythmApp"))
  node_n2["Main Activity<br/>[MainActivity.kt]"]
  node_n3["Service Activities<br/>activity set"]
end

subgraph group_core["Core & Shared"]
  node_n4["Core Domain<br/>domain contracts<br/>[PlayableItem.kt]"]
  node_n5["Music Repo<br/>repository contract<br/>[MusicRepository.kt]"]
  node_n6["Song UseCases<br/>use cases<br/>[SongUseCases.kt]"]
  node_n7["Shared Models<br/>shared data<br/>[Music.kt]"]
  node_n8[("Prefs & Stats<br/>shared repositories")]
  node_n9["Shared UI<br/>compose ui"]
  node_n10["Shared VM<br/>viewmodels<br/>[MusicViewModel.kt]"]
end

subgraph group_local["Local Music"]
  node_n11["Local Library<br/>feature module<br/>[HomeScreen.kt]"]
  node_n12[("Local DB<br/>room database<br/>[RhythmDatabase.kt]")]
  node_n13["Local Repo<br/>repository impl"]
  node_n14["Local VM<br/>feature viewmodel<br/>[MusicViewModel.kt]"]
end

subgraph group_streaming["Streaming Music"]
  node_n15["Streaming Stack<br/>feature module"]
  node_n16["Provider Clients<br/>api clients"]
  node_n17["Streaming Repo<br/>repository impl"]
end

subgraph group_infra["Infrastructure"]
  node_n18["Player Engine<br/>playback engine"]
  node_n19{{"Audio Chain<br/>audio processing"}}
  node_n20["Network Layer<br/>network services<br/>[NetworkClient.kt]"]
  node_n21["Widgets & Workers<br/>system integration<br/>[WidgetUpdater.kt]"]
  node_n22["Utilities<br/>app helpers"]
end

node_n1 -->|"starts"| node_n2
node_n2 -->|"navigates"| node_n9
node_n2 -.->|"launches"| node_n3
node_n9 -->|"binds state"| node_n10
node_n10 -->|"reads/writes"| node_n8
node_n10 -->|"depends on"| node_n4
node_n10 -->|"queries"| node_n5
node_n6 -->|"orchestrates"| node_n5
node_n11 -->|"drives"| node_n14
node_n14 -->|"uses"| node_n13
node_n13 -->|"persists"| node_n12
node_n13 -->|"implements"| node_n5
node_n15 -->|"drives"| node_n17
node_n17 -->|"calls"| node_n16
node_n17 -->|"implements"| node_n5
node_n18 -->|"processes audio"| node_n19
node_n18 -->|"consults"| node_n22
node_n18 -->|"broadcasts"| node_n21
node_n18 -->|"controls"| node_n3
node_n20 -.->|"feeds"| node_n15
node_n20 -.->|"supports"| node_n17
node_n20 -.->|"updates"| node_n10
node_n22 -.->|"supports"| node_n18
node_n7 -.->|"renders in"| node_n9
node_n7 -.->|"stored by"| node_n8
node_n4 -.->|"used by"| node_n11
node_n4 -.->|"used by"| node_n15

click node_n1 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/RhythmApplication.kt"
click node_n2 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/activities/MainActivity.kt"
click node_n3 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/activities/ExternalPlaybackActivity.kt"
click node_n4 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/core/domain/model/PlayableItem.kt"
click node_n5 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/core/domain/repository/MusicRepository.kt"
click node_n6 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/core/domain/usecase/SongUseCases.kt"
click node_n7 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/data/model/Music.kt"
click node_n8 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/data/repository/UserPreferencesRepository.kt"
click node_n9 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/presentation/navigation/RhythmNavigation.kt"
click node_n10 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/presentation/viewmodel/MusicViewModel.kt"
click node_n11 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/local/presentation/screens/HomeScreen.kt"
click node_n12 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/local/data/database/RhythmDatabase.kt"
click node_n13 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/local/data/repository/MusicRepositoryImpl.kt"
click node_n14 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/local/presentation/viewmodel/MusicViewModel.kt"
click node_n15 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/streaming/presentation/screens/StreamingHomeScreen.kt"
click node_n16 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/streaming/data/provider/JellyfinApiClient.kt"
click node_n17 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/streaming/data/repository/StreamingMusicRepositoryImpl.kt"
click node_n18 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/service/MediaPlaybackService.kt"
click node_n19 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/audio/RhythmAudioProcessor.kt"
click node_n20 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/network/NetworkClient.kt"
click node_n21 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/widget/WidgetUpdater.kt"
click node_n22 "https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/util/AudioDeviceManager.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_n1,node_n2,node_n3 toneBlue
class node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10 toneAmber
class node_n11,node_n12,node_n13,node_n14 toneMint
class node_n15,node_n16,node_n17 toneRose
class node_n18,node_n19,node_n20,node_n21,node_n22 toneIndigo
```

## Components

### App Shell

Process entry, activities, and build/distribution boundaries.

- [RhythmApp](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/RhythmApplication.kt): application · Process-level application entry point. · `app/src/main/java/chromahub/rhythm/app/RhythmApplication.kt`
- [Main Activity](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/activities/MainActivity.kt): activity · Primary Compose host and navigation entry. · `app/src/main/java/chromahub/rhythm/app/activities/MainActivity.kt`
- [Service Activities](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/activities/ExternalPlaybackActivity.kt): activity set · External playback, crash, and guard-timeout UI surfaces. · `app/src/main/java/chromahub/rhythm/app/activities/ExternalPlaybackActivity.kt`

### Core & Shared

Domain contracts, shared models, state, and reusable UI.

- [Core Domain](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/core/domain/model/PlayableItem.kt): domain contracts · Shared playback concepts and repository/use-case boundaries. · `app/src/main/java/chromahub/rhythm/app/core/domain/model/PlayableItem.kt`
- [Music Repo](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/core/domain/repository/MusicRepository.kt): repository contract · App-wide music data abstraction used by UI and viewmodels. · `app/src/main/java/chromahub/rhythm/app/core/domain/repository/MusicRepository.kt`
- [Song UseCases](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/core/domain/usecase/SongUseCases.kt): use cases · Orchestrates domain actions over music sources. · `app/src/main/java/chromahub/rhythm/app/core/domain/usecase/SongUseCases.kt`
- [Shared Models](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/data/model/Music.kt): shared data · App settings, music metadata, lyrics, transitions, and audio device models. · `app/src/main/java/chromahub/rhythm/app/shared/data/model/Music.kt`
- [Prefs & Stats](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/data/repository/UserPreferencesRepository.kt): shared repositories · Persistent preferences and listening statistics. · `app/src/main/java/chromahub/rhythm/app/shared/data/repository/UserPreferencesRepository.kt`
- [Shared UI](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/presentation/navigation/RhythmNavigation.kt): compose ui · Reusable player, settings, dialogs, theme, and navigation components. · `app/src/main/java/chromahub/rhythm/app/shared/presentation/navigation/RhythmNavigation.kt`
- [Shared VM](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/shared/presentation/viewmodel/MusicViewModel.kt): viewmodels · Bridges repositories into global UI state and app mode/theme/update flows. · `app/src/main/java/chromahub/rhythm/app/shared/presentation/viewmodel/MusicViewModel.kt`

### Local Music

On-device library, Room persistence, and local playback UI.

- [Local Library](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/local/presentation/screens/HomeScreen.kt): feature module · On-device music experience with library, playlists, onboarding, and equalizer screens. · `app/src/main/java/chromahub/rhythm/app/features/local/presentation/screens/HomeScreen.kt`
- [Local DB](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/local/data/database/RhythmDatabase.kt): room database · Song, artist, and join-table persistence for the local library. · `app/src/main/java/chromahub/rhythm/app/features/local/data/database/RhythmDatabase.kt`
- [Local Repo](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/local/data/repository/MusicRepositoryImpl.kt): repository impl · Implements local music access on top of Room and media data. · `app/src/main/java/chromahub/rhythm/app/features/local/data/repository/MusicRepositoryImpl.kt`
- [Local VM](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/local/presentation/viewmodel/MusicViewModel.kt): feature viewmodel · Coordinates local library state, queue state, and notification metadata. · `app/src/main/java/chromahub/rhythm/app/features/local/presentation/viewmodel/MusicViewModel.kt`

### Streaming Music

Remote-provider models, repositories, and setup flows.

- [Streaming Stack](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/streaming/presentation/screens/StreamingHomeScreen.kt): feature module · Remote playback domain, provider clients, repositories, and setup screens. · `app/src/main/java/chromahub/rhythm/app/features/streaming/presentation/screens/StreamingHomeScreen.kt`
- [Provider Clients](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/streaming/data/provider/JellyfinApiClient.kt): api clients · Jellyfin and Subsonic clients plus provider models. · `app/src/main/java/chromahub/rhythm/app/features/streaming/data/provider/JellyfinApiClient.kt`
- [Streaming Repo](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/features/streaming/data/repository/StreamingMusicRepositoryImpl.kt): repository impl · Streaming music repository and session persistence. · `app/src/main/java/chromahub/rhythm/app/features/streaming/data/repository/StreamingMusicRepositoryImpl.kt`

### Infrastructure

Playback engine, audio processing, network clients, widgets, and workers.

- [Player Engine](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/service/MediaPlaybackService.kt): playback engine · Long-lived media playback service and engine orchestration. · `app/src/main/java/chromahub/rhythm/app/infrastructure/service/MediaPlaybackService.kt`
- [Audio Chain](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/audio/RhythmAudioProcessor.kt): audio processing · Bass boost, spatialization, replaygain, and dynamic range processing. · `app/src/main/java/chromahub/rhythm/app/infrastructure/audio/RhythmAudioProcessor.kt`
- [Network Layer](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/network/NetworkClient.kt): network services · HTTP clients for metadata, lyrics, search, and update data. · `app/src/main/java/chromahub/rhythm/app/infrastructure/network/NetworkClient.kt`
- [Widgets & Workers](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/infrastructure/widget/WidgetUpdater.kt): system integration · Home-screen widgets, update workers, backup tasks, and pulse notifications. · `app/src/main/java/chromahub/rhythm/app/infrastructure/widget/WidgetUpdater.kt`
- [Utilities](https://github.com/cromaguy/rhythm/blob/main/app/src/main/java/chromahub/rhythm/app/util/AudioDeviceManager.kt): app helpers · Audio device, cache, lyrics, crash, and playback helper utilities. · `app/src/main/java/chromahub/rhythm/app/util/AudioDeviceManager.kt`

## Connections

- RhythmApp → Main Activity: starts · Application bootstraps the main UI host.
- Main Activity → Shared UI: navigates · Main activity renders the shared navigation and reusable UI.
- Main Activity → Service Activities: launches · Activity layer also handles external playback, crash, and guard flows.
- Shared UI → Shared VM: binds state · Shared UI is driven by global viewmodels.
- Shared VM → Prefs & Stats: reads/writes · Viewmodels persist settings and stats through shared repositories.
- Shared VM → Core Domain: depends on · Global state is expressed in core domain concepts.
- Shared VM → Music Repo: queries · Shared viewmodels use the music repository contract.
- Song UseCases → Music Repo: orchestrates · Use cases execute through the repository boundary.
- Local Library → Local VM: drives · Local screens are backed by the local feature viewmodel.
- Local VM → Local Repo: uses · Local viewmodel delegates to the Room-backed repository implementation.
- Local Repo → Local DB: persists · Local repository reads and writes the library database.
- Local Repo → Music Repo: implements · Local repository fulfills the app-wide music contract.
- Streaming Stack → Streaming Repo: drives · Streaming screens depend on the streaming repository layer.
- Streaming Repo → Provider Clients: calls · Streaming repository talks to provider clients and models.
- Streaming Repo → Music Repo: implements · Streaming repository also fulfills the shared music contract.
- Player Engine → Audio Chain: processes audio · Playback service applies enhancement and replaygain processing.
- Player Engine → Utilities: consults · Service relies on helpers for queues, cache, devices, and transfers.
- Player Engine → Widgets & Workers: broadcasts · Playback state feeds widgets and background workers.
- Player Engine → Service Activities: controls · External playback and guard flows connect back to the service boundary.
- Network Layer → Streaming Stack: feeds · Network metadata and provider data support streaming flows.
- Network Layer → Streaming Repo: supports · Streaming repository uses network client services as needed.
- Network Layer → Shared VM: updates · Network-backed update checks surface in shared app state.
- Utilities → Player Engine: supports · Utilities influence playback, devices, lyrics, crashes, and caching.
- Shared Models → Shared UI: renders in · Shared models inform UI state and screens.
- Shared Models → Prefs & Stats: stored by · Settings and listening-related models persist through repositories.
- Core Domain → Local Library: used by · Local feature screens consume the domain layer.
- Core Domain → Streaming Stack: used by · Streaming feature screens consume the same core abstractions.
