# devcodermax/echo-music architecture

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

## Overview

Echo Music is an Android music-streaming app. The principal workflow is user discovery or search, retrieval and parsing of music data, then playback through a background media service; library, lyrics, offline playback, and personalization are supporting branches. The README documents MVVM and the app’s integrations, while sampled source confirms the Room store, Spotify client, playlist manager, and media-service wiring. Some feature implementations are unsampled, so their internal connections are shown only where supported by the documented architecture or tree.

Main entry points: [`app/src/main/java/com/maxrave/echo/data/repository/MainRepository.kt`](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/repository/MainRepository.kt) (Main repository), [`app/src/main/java/com/maxrave/echo/viewModel`](https://github.com/devcodermax/echo-music/tree/main/app/src/main/java/com/maxrave/echo/viewModel) (View models), [`app/src/main/java/com/maxrave/echo/service/SimpleMediaService.kt`](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/service/SimpleMediaService.kt) (Media service), [`app/src/main/java/com/maxrave/echo/data/db/LocalDataSource.kt`](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/db/LocalDataSource.kt) (Local data source)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_activity["Main activity<br/>[MainActivity.kt]"]
  node_screens["Screens and navigation"]
  node_viewmodels["View models"]
end

subgraph group_discovery["Discovery and data"]
  node_repository["Main repository<br/>[MainRepository.kt]"]
  node_parsers["Content parsers"]
  node_lyrics["Synced lyrics<br/>[Lyrics.kt]"]
end

subgraph group_playback["Playback"]
  node_media_service["Media service"]
  node_media_handler["Playback handler"]
  node_media_di["Media service wiring"]
  node_player_ui["Player screens"]
  node_download_cache[("Offline and cache")]
end

subgraph group_library["Library and settings"]
  node_room_access["Local data source<br/>[LocalDataSource.kt]"]
  node_dao["Database access<br/>[DatabaseDao.kt]"]
  node_database[("Room database<br/>[MusicDatabase.kt]")]
  node_playlist_manager["Playlist manager"]
  node_settings[("Settings store")]
end

subgraph group_integrations["External integrations"]
  node_ytmusic["YouTube Music scraper<br/>[YouTube.kt]"]
  node_spotify["Spotify client<br/>[SpotifyClient.kt]"]
  node_ai["AI service<br/>[AiService.kt]"]
end

node_listener(("Listener"))
node_music_services(("Music services"))
node_ai_providers(("AI providers"))

node_listener -->|"opens"| node_activity
node_activity -->|"hosts"| node_screens
node_screens -->|"requests data"| node_viewmodels
node_viewmodels -->|"requests content"| node_repository
node_repository -->|"fetches music"| node_ytmusic
node_repository -->|"parses responses"| node_parsers
node_repository -.->|"uses Spotify"| node_spotify
node_ai -.->|"requests completions"| node_ai_providers
node_viewmodels -.->|"requests suggestions"| node_ai
node_media_service -->|"loads services"| node_media_di
node_media_service -->|"delegates playback"| node_media_handler
node_media_handler -->|"resolves streams"| node_repository
node_media_di -->|"configures cache"| node_download_cache
node_player_ui -->|"controls playback"| node_media_service
node_viewmodels -->|"reads and writes"| node_room_access
node_room_access -->|"queries"| node_dao
node_dao -->|"reads and writes"| node_database
node_playlist_manager -->|"manages playlists"| node_room_access
node_playlist_manager -->|"syncs playlists"| node_ytmusic
node_viewmodels -->|"reads and updates"| node_settings
node_repository -->|"provides lyric data"| node_lyrics
node_spotify -->|"calls Spotify APIs"| node_music_services
node_ytmusic -->|"retrieves music data"| node_music_services

click node_activity "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/ui/MainActivity.kt"
click node_screens "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/ui/navigation/graph/AppNavigationGraph.kt"
click node_viewmodels "https://github.com/devcodermax/echo-music/tree/main/app/src/main/java/com/maxrave/echo/viewModel"
click node_repository "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/repository/MainRepository.kt"
click node_parsers "https://github.com/devcodermax/echo-music/tree/main/app/src/main/java/com/maxrave/echo/data/parser"
click node_ytmusic "https://github.com/devcodermax/echo-music/blob/main/kotlinYtmusicScraper/src/main/java/com/maxrave/kotlinytmusicscraper/YouTube.kt"
click node_spotify "https://github.com/devcodermax/echo-music/blob/main/spotify/src/main/java/com/maxrave/spotify/SpotifyClient.kt"
click node_ai "https://github.com/devcodermax/echo-music/blob/main/aiService/src/main/java/org/simpmusic/aiservice/AiService.kt"
click node_media_service "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/service/SimpleMediaService.kt"
click node_media_handler "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/service/SimpleMediaServiceHandler.kt"
click node_media_di "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/di/MediaServiceModule.kt"
click node_player_ui "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/ui/screen/player/NowPlayingScreen.kt"
click node_room_access "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/db/LocalDataSource.kt"
click node_dao "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/db/DatabaseDao.kt"
click node_database "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/db/MusicDatabase.kt"
click node_playlist_manager "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/manager/LocalPlaylistManager.kt"
click node_settings "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/dataStore/DataStoreManager.kt"
click node_download_cache "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/di/MediaServiceModule.kt"
click node_lyrics "https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/model/metadata/Lyrics.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_screens,node_viewmodels toneBlue
class node_repository,node_parsers,node_lyrics toneAmber
class node_media_service,node_media_handler,node_media_di,node_player_ui,node_download_cache toneMint
class node_room_access,node_dao,node_database,node_playlist_manager,node_settings toneRose
class node_ytmusic,node_spotify,node_ai,node_listener,node_music_services,node_ai_providers toneIndigo
```

## Components

### App experience

- [Main activity](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/ui/MainActivity.kt): `app/src/main/java/com/maxrave/echo/ui/MainActivity.kt`
- [Screens and navigation](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/ui/navigation/graph/AppNavigationGraph.kt): `app/src/main/java/com/maxrave/echo/ui/navigation/graph/AppNavigationGraph.kt`
- [View models](https://github.com/devcodermax/echo-music/tree/main/app/src/main/java/com/maxrave/echo/viewModel): `app/src/main/java/com/maxrave/echo/viewModel`

### Discovery and data

- [Main repository](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/repository/MainRepository.kt): `app/src/main/java/com/maxrave/echo/data/repository/MainRepository.kt`
- [Content parsers](https://github.com/devcodermax/echo-music/tree/main/app/src/main/java/com/maxrave/echo/data/parser): `app/src/main/java/com/maxrave/echo/data/parser`
- [Synced lyrics](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/model/metadata/Lyrics.kt): `app/src/main/java/com/maxrave/echo/data/model/metadata/Lyrics.kt`

### Playback

- [Media service](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/service/SimpleMediaService.kt): `app/src/main/java/com/maxrave/echo/service/SimpleMediaService.kt`
- [Playback handler](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/service/SimpleMediaServiceHandler.kt): `app/src/main/java/com/maxrave/echo/service/SimpleMediaServiceHandler.kt`
- [Media service wiring](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/di/MediaServiceModule.kt): `app/src/main/java/com/maxrave/echo/di/MediaServiceModule.kt`
- [Player screens](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/ui/screen/player/NowPlayingScreen.kt): `app/src/main/java/com/maxrave/echo/ui/screen/player/NowPlayingScreen.kt`
- [Offline and cache](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/di/MediaServiceModule.kt): `app/src/main/java/com/maxrave/echo/di/MediaServiceModule.kt`

### Library and settings

- [Local data source](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/db/LocalDataSource.kt): `app/src/main/java/com/maxrave/echo/data/db/LocalDataSource.kt`
- [Database access](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/db/DatabaseDao.kt): `app/src/main/java/com/maxrave/echo/data/db/DatabaseDao.kt`
- [Room database](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/db/MusicDatabase.kt): `app/src/main/java/com/maxrave/echo/data/db/MusicDatabase.kt`
- [Playlist manager](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/manager/LocalPlaylistManager.kt): `app/src/main/java/com/maxrave/echo/data/manager/LocalPlaylistManager.kt`
- [Settings store](https://github.com/devcodermax/echo-music/blob/main/app/src/main/java/com/maxrave/echo/data/dataStore/DataStoreManager.kt): `app/src/main/java/com/maxrave/echo/data/dataStore/DataStoreManager.kt`

### External integrations

- [YouTube Music scraper](https://github.com/devcodermax/echo-music/blob/main/kotlinYtmusicScraper/src/main/java/com/maxrave/kotlinytmusicscraper/YouTube.kt): `kotlinYtmusicScraper/src/main/java/com/maxrave/kotlinytmusicscraper/YouTube.kt`
- [Spotify client](https://github.com/devcodermax/echo-music/blob/main/spotify/src/main/java/com/maxrave/spotify/SpotifyClient.kt): `spotify/src/main/java/com/maxrave/spotify/SpotifyClient.kt`
- [AI service](https://github.com/devcodermax/echo-music/blob/main/aiService/src/main/java/org/simpmusic/aiservice/AiService.kt): `aiService/src/main/java/org/simpmusic/aiservice/AiService.kt`

### Other components

- **Listener**
- **Music services**
- **AI providers**

## Connections

- Listener → Main activity: opens
- Main activity → Screens and navigation: hosts
- Screens and navigation → View models: requests data
- View models → Main repository: requests content
- Main repository → YouTube Music scraper: fetches music
- Main repository → Content parsers: parses responses
- Main repository → Spotify client: uses Spotify
- AI service → AI providers: requests completions
- View models → AI service: requests suggestions
- Media service → Media service wiring: loads services
- Media service → Playback handler: delegates playback
- Playback handler → Main repository: resolves streams
- Media service wiring → Offline and cache: configures cache
- Player screens → Media service: controls playback
- View models → Local data source: reads and writes
- Local data source → Database access: queries
- Database access → Room database: reads and writes
- Playlist manager → Local data source: manages playlists
- Playlist manager → YouTube Music scraper: syncs playlists
- View models → Settings store: reads and updates
- Main repository → Synced lyrics: provides lyric data
- Spotify client → Music services: calls Spotify APIs
- YouTube Music scraper → Music services: retrieves music data