# marlo4220mc/harmony-music architecture

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

- Interactive diagram: https://gitdiagram.com/marlo4220mc/harmony-music
- Repository: https://github.com/marlo4220mc/harmony-music

## Overview

Harmony Music is a cross-platform Flutter music-streaming app. Users discover music, select tracks or radio, and play them with background playback; they can also manage playlists and bookmarks, download tracks, view lyrics, and connect Piped playlists. The graph reflects README-documented capabilities and the source tree’s module boundaries. Dart implementation excerpts were not provided, so internal call ownership is uncertain; relationships between those modules are intentionally limited.

Main entry points: [`lib/ui/player/player.dart`](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/player/player.dart) (Player UI), [`lib/services/audio_handler.dart`](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/audio_handler.dart) (Audio handler), [`lib/main.dart`](https://github.com/marlo4220mc/harmony-music/blob/main/lib/main.dart) (App entry), [`lib/ui/navigator.dart`](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/navigator.dart) (Navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_entry["App entry<br/>[main.dart]"]
  node_navigation["Navigation<br/>[navigator.dart]"]
  node_home["Home<br/>[home_screen.dart]"]
end

subgraph group_discovery["Music discovery"]
  node_search["Search<br/>[search_screen.dart]"]
  node_searchresults["Search results"]
  node_musicapi["Music service<br/>[music_service.dart]"]
  node_albumsartists["Albums and artists<br/>[album_screen.dart]"]
end

subgraph group_playback["Playback"]
  node_player["Player UI<br/>[player.dart]"]
  node_playercontroller["Player controller"]
  node_audiohandler["Audio handler<br/>[audio_handler.dart]"]
  node_stream["Stream service"]
  node_background["Background playback"]
  node_downloader["Downloads and cache<br/>[downloader.dart]"]
  node_lyrics["Lyrics"]
  node_equalizer["Equalizer<br/>[equalizer.dart]"]
end

subgraph group_library["Library and integrations"]
  node_library["Library<br/>[library.dart]"]
  node_playlist["Playlist management"]
  node_playliststore[("Playlist state")]
  node_piped["Piped integration<br/>[piped_service.dart]"]
end

node_user(("Listener"))
node_youtube["YouTube music"]
node_pipedservice["Piped service"]

node_user -->|"launches"| node_entry
node_entry -->|"starts"| node_navigation
node_navigation -->|"routes to"| node_home
node_user -->|"searches"| node_search
node_search -->|"opens results"| node_searchresults
node_searchresults -->|"requests music"| node_musicapi
node_musicapi -->|"queries"| node_youtube
node_user -->|"browses"| node_albumsartists
node_user -->|"selects music"| node_player
node_player -->|"controls"| node_playercontroller
node_playercontroller -->|"dispatches playback"| node_audiohandler
node_audiohandler -->|"requests streams"| node_stream
node_stream -->|"gets stream URL"| node_youtube
node_audiohandler -->|"supports background audio"| node_background
node_user -->|"downloads tracks"| node_downloader
node_user -->|"views lyrics"| node_lyrics
node_user -->|"manages saved music"| node_library
node_user -->|"manages playlists"| node_playlist
node_playlist -->|"persists state"| node_playliststore
node_piped -.->|"integrates playlists"| node_pipedservice
node_player -->|"adjusts audio"| node_equalizer

click node_entry "https://github.com/marlo4220mc/harmony-music/blob/main/lib/main.dart"
click node_navigation "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/navigator.dart"
click node_home "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Home/home_screen.dart"
click node_search "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Search/search_screen.dart"
click node_searchresults "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Search/search_result_screen.dart"
click node_musicapi "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/music_service.dart"
click node_albumsartists "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Album/album_screen.dart"
click node_player "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/player/player.dart"
click node_playercontroller "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/player/player_controller.dart"
click node_audiohandler "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/audio_handler.dart"
click node_stream "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/stream_service.dart"
click node_background "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/background_task.dart"
click node_downloader "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/downloader.dart"
click node_lyrics "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/synced_lyrics_service.dart"
click node_library "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Library/library.dart"
click node_playlist "https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Playlist/playlist_screen.dart"
click node_playliststore "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/continue_playlists_store.dart"
click node_piped "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/piped_service.dart"
click node_equalizer "https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/equalizer.dart"

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_entry,node_navigation,node_home toneBlue
class node_search,node_searchresults,node_musicapi,node_albumsartists toneAmber
class node_player,node_playercontroller,node_audiohandler,node_stream,node_background,node_downloader,node_lyrics,node_equalizer toneMint
class node_library,node_playlist,node_playliststore,node_piped toneRose
class node_user,node_youtube,node_pipedservice toneIndigo
```

## Components

### App experience

- [App entry](https://github.com/marlo4220mc/harmony-music/blob/main/lib/main.dart): `lib/main.dart`
- [Navigation](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/navigator.dart): `lib/ui/navigator.dart`
- [Home](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Home/home_screen.dart): `lib/ui/screens/Home/home_screen.dart`

### Music discovery

- [Search](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Search/search_screen.dart): `lib/ui/screens/Search/search_screen.dart`
- [Search results](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Search/search_result_screen.dart): `lib/ui/screens/Search/search_result_screen.dart`
- [Music service](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/music_service.dart): `lib/services/music_service.dart`
- [Albums and artists](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Album/album_screen.dart): `lib/ui/screens/Album/album_screen.dart`

### Playback

- [Player UI](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/player/player.dart): `lib/ui/player/player.dart`
- [Player controller](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/player/player_controller.dart): `lib/ui/player/player_controller.dart`
- [Audio handler](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/audio_handler.dart): `lib/services/audio_handler.dart`
- [Stream service](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/stream_service.dart): `lib/services/stream_service.dart`
- [Background playback](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/background_task.dart): `lib/services/background_task.dart`
- [Downloads and cache](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/downloader.dart): `lib/services/downloader.dart`
- [Lyrics](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/synced_lyrics_service.dart): `lib/services/synced_lyrics_service.dart`
- [Equalizer](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/equalizer.dart): `lib/services/equalizer.dart`

### Library and integrations

- [Library](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Library/library.dart): `lib/ui/screens/Library/library.dart`
- [Playlist management](https://github.com/marlo4220mc/harmony-music/blob/main/lib/ui/screens/Playlist/playlist_screen.dart): `lib/ui/screens/Playlist/playlist_screen.dart`
- [Playlist state](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/continue_playlists_store.dart): `lib/services/continue_playlists_store.dart`
- [Piped integration](https://github.com/marlo4220mc/harmony-music/blob/main/lib/services/piped_service.dart): `lib/services/piped_service.dart`

### Other components

- **Listener**
- **YouTube music**
- **Piped service**

## Connections

- Listener → App entry: launches
- App entry → Navigation: starts
- Navigation → Home: routes to
- Listener → Search: searches
- Search → Search results: opens results
- Search results → Music service: requests music
- Music service → YouTube music: queries
- Listener → Albums and artists: browses
- Listener → Player UI: selects music
- Player UI → Player controller: controls
- Player controller → Audio handler: dispatches playback
- Audio handler → Stream service: requests streams
- Stream service → YouTube music: gets stream URL
- Audio handler → Background playback: supports background audio
- Listener → Downloads and cache: downloads tracks
- Listener → Lyrics: views lyrics
- Listener → Library: manages saved music
- Listener → Playlist management: manages playlists
- Playlist management → Playlist state: persists state
- Piped integration → Piped service: integrates playlists
- Player UI → Equalizer: adjusts audio