# hamza-houaoui/podium-music-player architecture

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

- Interactive diagram: https://gitdiagram.com/hamza-houaoui/podium-music-player
- Repository: https://github.com/hamza-houaoui/podium-music-player

## Overview

CHORT is an Android retro-styled music player. A listener enters through the device UI, browses local or online music, and starts playback; the playback service manages the queue and audio, with background and remote controls. Separate product branches cover lyrics, radio, podcasts, Quran, books, and device customization. The tree and README identify these capabilities, while sampled source confirms key UI, composition, database, and playback connections; unsampled feature wiring is intentionally left implicit.

Main entry points: [`app/src/main/kotlin/app/podium/AppGraph.kt`](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/AppGraph.kt) (App composition), [`player/service/src/main/kotlin/app/podium/player/service/PodiumPlaybackEngine.kt`](https://github.com/hamza-houaoui/podium-music-player/blob/main/player/service/src/main/kotlin/app/podium/player/service/PodiumPlaybackEngine.kt) (Playback engine), [`sources/api/src/main/kotlin/app/podium/sources/api/SourceRegistry.kt`](https://github.com/hamza-houaoui/podium-music-player/blob/main/sources/api/src/main/kotlin/app/podium/sources/api/SourceRegistry.kt) (Music sources), [`app/src/main/kotlin/app/podium/MainActivity.kt`](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/MainActivity.kt) (Android entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and experience"]
  node_activity["Android entry<br/>[MainActivity.kt]"]
  node_app_ui["Device UI<br/>[PodiumApp.kt]"]
  node_composition["App composition<br/>[AppGraph.kt]"]
end

subgraph group_music["Music discovery"]
  node_library_ui["Library browse<br/>[LibraryScreens.kt]"]
  node_library_repo["Local library"]
  node_online_ui["Online catalogue<br/>[OnlineScreens.kt]"]
  node_online_repo["Online access"]
  node_source_registry["Music sources<br/>[SourceRegistry.kt]"]
  node_youtube_source["YouTube Music"]
end

subgraph group_playback["Playback"]
  node_player_api["Playback controls"]
  node_queue["Queue manager<br/>[QueueManager.kt]"]
  node_service["Playback service<br/>[PlaybackService.kt]"]
  node_engine["Playback engine"]
  node_stream_resolver["Stream resolution<br/>[StreamResolver.kt]"]
end

subgraph group_content["Media experiences"]
  node_lyrics["Synchronized lyrics"]
  node_radio["Radio browser<br/>[RadioScreens.kt]"]
  node_podcasts["Podcasts<br/>[PodcastScreens.kt]"]
  node_quran["Quran reader<br/>[QuranScreens.kt]"]
  node_books["Books<br/>[BookRepository.kt]"]
end

subgraph group_platform["Persistence and device"]
  node_database[("App database<br/>[PodiumDatabase.kt]")]
  node_settings["Device settings<br/>[SettingsScreens.kt]"]
  node_downloads["Offline downloads"]
  node_design["Device appearance"]
end

node_listener(("Listener"))

node_listener -->|"opens app"| node_activity
node_activity -->|"shows UI"| node_app_ui
node_app_ui -->|"uses graph"| node_composition
node_listener -->|"browses music"| node_library_ui
node_library_ui -->|"loads library"| node_library_repo
node_listener -->|"searches catalogue"| node_online_ui
node_online_ui -->|"requests catalogue"| node_online_repo
node_composition -->|"registers sources"| node_source_registry
node_composition -->|"configures library"| node_library_repo
node_online_repo -.->|"uses sources"| node_source_registry
node_source_registry -.->|"registers provider"| node_youtube_source
node_listener -->|"controls playback"| node_player_api
node_player_api -.->|"controls service"| node_service
node_service -->|"creates engine"| node_engine
node_engine -->|"mutates queue"| node_queue
node_engine -->|"resolves streams"| node_stream_resolver
node_composition -.->|"provides persistence"| node_database
node_listener -->|"views lyrics"| node_lyrics
node_listener -->|"browses radio"| node_radio
node_listener -->|"explores podcasts"| node_podcasts
node_listener -->|"reads Quran"| node_quran
node_listener -.->|"uses books"| node_books
node_listener -->|"customizes device"| node_settings
node_listener -.->|"downloads media"| node_downloads
node_settings -.->|"changes appearance"| node_design

click node_activity "https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/MainActivity.kt"
click node_app_ui "https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/PodiumApp.kt"
click node_composition "https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/AppGraph.kt"
click node_library_ui "https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/library/src/main/kotlin/app/podium/feature/library/LibraryScreens.kt"
click node_library_repo "https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/library/src/main/kotlin/app/podium/feature/library/LibraryRepository.kt"
click node_online_ui "https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/online/src/main/kotlin/app/podium/feature/online/OnlineScreens.kt"
click node_online_repo "https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/online/src/main/kotlin/app/podium/feature/online/OnlineRepository.kt"
click node_source_registry "https://github.com/hamza-houaoui/podium-music-player/blob/main/sources/api/src/main/kotlin/app/podium/sources/api/SourceRegistry.kt"
click node_youtube_source "https://github.com/hamza-houaoui/podium-music-player/blob/main/sources/youtubemusic/src/main/kotlin/app/podium/sources/youtubemusic/YouTubeMusicSource.kt"
click node_player_api "https://github.com/hamza-houaoui/podium-music-player/blob/main/player/api/src/main/kotlin/app/podium/player/api/OwnerAwarePlaybackController.kt"
click node_queue "https://github.com/hamza-houaoui/podium-music-player/blob/main/player/api/src/main/kotlin/app/podium/player/api/QueueManager.kt"
click node_service "https://github.com/hamza-houaoui/podium-music-player/blob/main/player/service/src/main/kotlin/app/podium/player/service/PlaybackService.kt"
click node_engine "https://github.com/hamza-houaoui/podium-music-player/blob/main/player/service/src/main/kotlin/app/podium/player/service/PodiumPlaybackEngine.kt"
click node_stream_resolver "https://github.com/hamza-houaoui/podium-music-player/blob/main/sources/api/src/main/kotlin/app/podium/sources/api/resolve/StreamResolver.kt"
click node_lyrics "https://github.com/hamza-houaoui/podium-music-player/blob/main/core/lyrics/src/main/kotlin/app/podium/core/lyrics/LyricsRepository.kt"
click node_radio "https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/radio/RadioScreens.kt"
click node_podcasts "https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/podcast/PodcastScreens.kt"
click node_quran "https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/quran/QuranScreens.kt"
click node_books "https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/books/BookRepository.kt"
click node_database "https://github.com/hamza-houaoui/podium-music-player/blob/main/core/database/src/main/kotlin/app/podium/core/database/PodiumDatabase.kt"
click node_settings "https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/settings/src/main/kotlin/app/podium/feature/settings/SettingsScreens.kt"
click node_downloads "https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/downloads/OfflineDownloadManager.kt"
click node_design "https://github.com/hamza-houaoui/podium-music-player/blob/main/core/designsystem/src/main/kotlin/app/podium/core/designsystem/shell/DeviceAppearance.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_activity,node_app_ui,node_composition toneBlue
class node_library_ui,node_library_repo,node_online_ui,node_online_repo,node_source_registry,node_youtube_source toneAmber
class node_player_api,node_queue,node_service,node_engine,node_stream_resolver toneMint
class node_lyrics,node_radio,node_podcasts,node_quran,node_books toneRose
class node_database,node_settings,node_downloads,node_design,node_listener toneIndigo
```

## Components

### App and experience

- [Android entry](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/MainActivity.kt): `app/src/main/kotlin/app/podium/MainActivity.kt`
- [Device UI](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/PodiumApp.kt): `app/src/main/kotlin/app/podium/PodiumApp.kt`
- [App composition](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/AppGraph.kt): `app/src/main/kotlin/app/podium/AppGraph.kt`

### Music discovery

- [Library browse](https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/library/src/main/kotlin/app/podium/feature/library/LibraryScreens.kt): `feature/library/src/main/kotlin/app/podium/feature/library/LibraryScreens.kt`
- [Local library](https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/library/src/main/kotlin/app/podium/feature/library/LibraryRepository.kt): `feature/library/src/main/kotlin/app/podium/feature/library/LibraryRepository.kt`
- [Online catalogue](https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/online/src/main/kotlin/app/podium/feature/online/OnlineScreens.kt): `feature/online/src/main/kotlin/app/podium/feature/online/OnlineScreens.kt`
- [Online access](https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/online/src/main/kotlin/app/podium/feature/online/OnlineRepository.kt): `feature/online/src/main/kotlin/app/podium/feature/online/OnlineRepository.kt`
- [Music sources](https://github.com/hamza-houaoui/podium-music-player/blob/main/sources/api/src/main/kotlin/app/podium/sources/api/SourceRegistry.kt): `sources/api/src/main/kotlin/app/podium/sources/api/SourceRegistry.kt`
- [YouTube Music](https://github.com/hamza-houaoui/podium-music-player/blob/main/sources/youtubemusic/src/main/kotlin/app/podium/sources/youtubemusic/YouTubeMusicSource.kt): `sources/youtubemusic/src/main/kotlin/app/podium/sources/youtubemusic/YouTubeMusicSource.kt`

### Playback

- [Playback controls](https://github.com/hamza-houaoui/podium-music-player/blob/main/player/api/src/main/kotlin/app/podium/player/api/OwnerAwarePlaybackController.kt): `player/api/src/main/kotlin/app/podium/player/api/OwnerAwarePlaybackController.kt`
- [Queue manager](https://github.com/hamza-houaoui/podium-music-player/blob/main/player/api/src/main/kotlin/app/podium/player/api/QueueManager.kt): `player/api/src/main/kotlin/app/podium/player/api/QueueManager.kt`
- [Playback service](https://github.com/hamza-houaoui/podium-music-player/blob/main/player/service/src/main/kotlin/app/podium/player/service/PlaybackService.kt): `player/service/src/main/kotlin/app/podium/player/service/PlaybackService.kt`
- [Playback engine](https://github.com/hamza-houaoui/podium-music-player/blob/main/player/service/src/main/kotlin/app/podium/player/service/PodiumPlaybackEngine.kt): `player/service/src/main/kotlin/app/podium/player/service/PodiumPlaybackEngine.kt`
- [Stream resolution](https://github.com/hamza-houaoui/podium-music-player/blob/main/sources/api/src/main/kotlin/app/podium/sources/api/resolve/StreamResolver.kt): `sources/api/src/main/kotlin/app/podium/sources/api/resolve/StreamResolver.kt`

### Media experiences

- [Synchronized lyrics](https://github.com/hamza-houaoui/podium-music-player/blob/main/core/lyrics/src/main/kotlin/app/podium/core/lyrics/LyricsRepository.kt): `core/lyrics/src/main/kotlin/app/podium/core/lyrics/LyricsRepository.kt`
- [Radio browser](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/radio/RadioScreens.kt): `app/src/main/kotlin/app/podium/radio/RadioScreens.kt`
- [Podcasts](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/podcast/PodcastScreens.kt): `app/src/main/kotlin/app/podium/podcast/PodcastScreens.kt`
- [Quran reader](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/quran/QuranScreens.kt): `app/src/main/kotlin/app/podium/quran/QuranScreens.kt`
- [Books](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/books/BookRepository.kt): `app/src/main/kotlin/app/podium/books/BookRepository.kt`

### Persistence and device

- [App database](https://github.com/hamza-houaoui/podium-music-player/blob/main/core/database/src/main/kotlin/app/podium/core/database/PodiumDatabase.kt): `core/database/src/main/kotlin/app/podium/core/database/PodiumDatabase.kt`
- [Device settings](https://github.com/hamza-houaoui/podium-music-player/blob/main/feature/settings/src/main/kotlin/app/podium/feature/settings/SettingsScreens.kt): `feature/settings/src/main/kotlin/app/podium/feature/settings/SettingsScreens.kt`
- [Offline downloads](https://github.com/hamza-houaoui/podium-music-player/blob/main/app/src/main/kotlin/app/podium/downloads/OfflineDownloadManager.kt): `app/src/main/kotlin/app/podium/downloads/OfflineDownloadManager.kt`
- [Device appearance](https://github.com/hamza-houaoui/podium-music-player/blob/main/core/designsystem/src/main/kotlin/app/podium/core/designsystem/shell/DeviceAppearance.kt): `core/designsystem/src/main/kotlin/app/podium/core/designsystem/shell/DeviceAppearance.kt`

### Other components

- **Listener**

## Connections

- Listener → Android entry: opens app (evidence: `README.md`)
- Android entry → Device UI: shows UI (evidence: `app/src/main/kotlin/app/podium/MainActivity.kt`)
- Device UI → App composition: uses graph (evidence: `app/src/main/kotlin/app/podium/MainActivity.kt`)
- Listener → Library browse: browses music (evidence: `README.md`)
- Library browse → Local library: loads library (evidence: `feature/library/src/main/kotlin/app/podium/feature/library/LibraryRepository.kt`)
- Listener → Online catalogue: searches catalogue (evidence: `README.md`)
- Online catalogue → Online access: requests catalogue (evidence: `feature/online/src/main/kotlin/app/podium/feature/online/OnlineRepository.kt`)
- App composition → Music sources: registers sources (evidence: `app/src/main/kotlin/app/podium/AppGraph.kt`)
- App composition → Local library: configures library (evidence: `app/src/main/kotlin/app/podium/AppGraph.kt`)
- Online access → Music sources: uses sources
- Music sources → YouTube Music: registers provider
- Listener → Playback controls: controls playback (evidence: `README.md`)
- Playback controls → Playback service: controls service
- Playback service → Playback engine: creates engine (evidence: `player/service/src/main/kotlin/app/podium/player/service/PlaybackService.kt`)
- Playback engine → Queue manager: mutates queue (evidence: `player/service/src/main/kotlin/app/podium/player/service/PodiumPlaybackEngine.kt`)
- Playback engine → Stream resolution: resolves streams (evidence: `player/service/src/main/kotlin/app/podium/player/service/PodiumPlaybackEngine.kt`)
- App composition → App database: provides persistence (evidence: `app/src/main/kotlin/app/podium/AppGraph.kt`)
- Listener → Synchronized lyrics: views lyrics (evidence: `README.md`)
- Listener → Radio browser: browses radio (evidence: `README.md`)
- Listener → Podcasts: explores podcasts (evidence: `README.md`)
- Listener → Quran reader: reads Quran (evidence: `README.md`)
- Listener → Books: uses books
- Listener → Device settings: customizes device (evidence: `README.md`)
- Listener → Offline downloads: downloads media
- Device settings → Device appearance: changes appearance
