# qiannqq/elia-music-desktop architecture

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

- Interactive diagram: https://gitdiagram.com/qiannqq/elia-music-desktop
- Repository: https://github.com/qiannqq/elia-music-desktop

## Overview

Elia Music is a Flutter Windows desktop music player. The principal workflow is searching QQ Music or NetEase Music, importing a song or playlist, then listening with synchronized lyrics or downloading tracks; local playlists, themes, video backgrounds and Windows integrations are supporting capabilities. The Dart implementation is represented at component or subsystem level because its source was not excerpted. Native runner relationships are shown where registration or calls are visible in the excerpts; other feature links rely on the README.

Main entry points: [`lib/services/player_controller.dart`](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/player_controller.dart) (Player Controller), [`windows/runner/flutter_window.cpp`](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/flutter_window.cpp) (Flutter Window), [`lib/ui/pages/search_page.dart`](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/pages/search_page.dart) (Search Page), [`lib/ui/pages/settings_page.dart`](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/pages/settings_page.dart) (Settings Page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_entry["App Entry<br/>[main.dart]"]
  node_shell["App Shell<br/>[app_shell.dart]"]
  node_state["App State<br/>[app_state.dart]"]
  node_search["Search Page<br/>[search_page.dart]"]
  node_playlist["Playlist Page<br/>[playlist_page.dart]"]
end

subgraph group_music["Music Services"]
  node_providers["Music Providers"]
  node_api["API Client<br/>[api_client.dart]"]
  node_song["Song Model<br/>[song.dart]"]
  node_playlistmodel["Playlist Model<br/>[playlist.dart]"]
  node_downloads[("Audio Cache<br/>[audio_cache.dart]")]
end

subgraph group_experience["Playback Experience"]
  node_player["Player Controller"]
  node_proxy["Local Audio Proxy<br/>[http_server.dart]"]
  node_lyrics["Lyrics Services<br/>[lyric_cache.dart]"]
  node_nowplaying["Now Playing<br/>[now_playing.dart]"]
  node_queue["Queue Panel<br/>[queue_panel.dart]"]
  node_background["Video Background<br/>[video_bg.dart]"]
end

subgraph group_preferences["Library And Settings"]
  node_localstore[("Local Store<br/>[local_store.dart]")]
  node_settings["Settings Page<br/>[settings_page.dart]"]
  node_theme["Theme Controller"]
end

subgraph group_windows["Windows Integration"]
  node_nativewindow["Flutter Window<br/>[flutter_window.cpp]"]
  node_smtc["SMTC Bridge<br/>[smtc_bridge.cpp]"]
  node_island["Lyric Island<br/>[lyric_island.cpp]"]
  node_probe["Audio Probe Bridge"]
  node_probealgo["Audio Probe<br/>[audio_probe.cpp]"]
  node_windowfx["Window Effects<br/>[window_fx.cpp]"]
  node_chrome["Window Chrome<br/>[window_chrome.cpp]"]
end

node_user(("Listener"))

node_user -->|"searches"| node_search
node_user -->|"imports playlists"| node_playlist
node_search -->|"searches catalogs"| node_providers
node_providers -.->|"uses API client"| node_api
node_search -.->|"shows results"| node_song
node_playlist -.->|"manages playlists"| node_playlistmodel
node_user -->|"listens"| node_player
node_player -->|"streams through"| node_proxy
node_player -->|"synchronizes lyrics"| node_lyrics
node_player -->|"downloads tracks"| node_downloads
node_player -.->|"updates display"| node_nowplaying
node_player -.->|"manages queue"| node_queue
node_settings -.->|"configures"| node_localstore
node_settings -->|"changes theme"| node_theme
node_background -.->|"provides backdrop"| node_nowplaying
node_nativewindow -->|"registers bridge"| node_smtc
node_nativewindow -->|"registers bridge"| node_island
node_nativewindow -->|"registers bridge"| node_probe
node_nativewindow -->|"registers bridge"| node_windowfx
node_probe -->|"invokes probe"| node_probealgo
node_nativewindow -->|"uses hit testing"| node_chrome

click node_entry "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/main.dart"
click node_shell "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/app_shell.dart"
click node_state "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/state/app_state.dart"
click node_search "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/pages/search_page.dart"
click node_playlist "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/pages/playlist_page.dart"
click node_providers "https://github.com/qiannqq/elia-music-desktop/tree/Flutter/lib/services"
click node_api "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/api_client.dart"
click node_song "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/models/song.dart"
click node_playlistmodel "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/models/playlist.dart"
click node_player "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/player_controller.dart"
click node_proxy "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/http_server.dart"
click node_lyrics "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/lyric_cache.dart"
click node_nowplaying "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/now_playing.dart"
click node_queue "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/widgets/queue_panel.dart"
click node_downloads "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/audio_cache.dart"
click node_localstore "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/core/local_store.dart"
click node_settings "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/pages/settings_page.dart"
click node_theme "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/state/theme_controller.dart"
click node_background "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/video_bg.dart"
click node_nativewindow "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/flutter_window.cpp"
click node_smtc "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/smtc_bridge.cpp"
click node_island "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/lyric_island.cpp"
click node_probe "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/audio_probe_bridge.cpp"
click node_probealgo "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/audio_probe.cpp"
click node_windowfx "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/window_fx.cpp"
click node_chrome "https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/window_chrome.cpp"

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_shell,node_state,node_search,node_playlist toneBlue
class node_providers,node_api,node_song,node_playlistmodel,node_downloads toneAmber
class node_player,node_proxy,node_lyrics,node_nowplaying,node_queue,node_background toneMint
class node_localstore,node_settings,node_theme toneRose
class node_nativewindow,node_smtc,node_island,node_probe,node_probealgo,node_windowfx,node_chrome,node_user toneIndigo
```

## Components

### Application

- [App Entry](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/main.dart): `lib/main.dart`
- [App Shell](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/app_shell.dart): `lib/ui/app_shell.dart`
- [App State](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/state/app_state.dart): `lib/state/app_state.dart`
- [Search Page](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/pages/search_page.dart): `lib/ui/pages/search_page.dart`
- [Playlist Page](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/pages/playlist_page.dart): `lib/ui/pages/playlist_page.dart`

### Music Services

- [Music Providers](https://github.com/qiannqq/elia-music-desktop/tree/Flutter/lib/services): `lib/services`
- [API Client](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/api_client.dart): `lib/services/api_client.dart`
- [Song Model](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/models/song.dart): `lib/models/song.dart`
- [Playlist Model](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/models/playlist.dart): `lib/models/playlist.dart`
- [Audio Cache](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/audio_cache.dart): `lib/services/audio_cache.dart`

### Playback Experience

- [Player Controller](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/player_controller.dart): `lib/services/player_controller.dart`
- [Local Audio Proxy](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/http_server.dart): `lib/services/http_server.dart`
- [Lyrics Services](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/lyric_cache.dart): `lib/services/lyric_cache.dart`
- [Now Playing](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/now_playing.dart): `lib/ui/now_playing.dart`
- [Queue Panel](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/widgets/queue_panel.dart): `lib/ui/widgets/queue_panel.dart`
- [Video Background](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/services/video_bg.dart): `lib/services/video_bg.dart`

### Library And Settings

- [Local Store](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/core/local_store.dart): `lib/core/local_store.dart`
- [Settings Page](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/ui/pages/settings_page.dart): `lib/ui/pages/settings_page.dart`
- [Theme Controller](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/lib/state/theme_controller.dart): `lib/state/theme_controller.dart`

### Windows Integration

- [Flutter Window](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/flutter_window.cpp): `windows/runner/flutter_window.cpp`
- [SMTC Bridge](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/smtc_bridge.cpp): `windows/runner/smtc_bridge.cpp`
- [Lyric Island](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/lyric_island.cpp): `windows/runner/lyric_island.cpp`
- [Audio Probe Bridge](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/audio_probe_bridge.cpp): `windows/runner/audio_probe_bridge.cpp`
- [Audio Probe](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/audio_probe.cpp): `windows/runner/audio_probe.cpp`
- [Window Effects](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/window_fx.cpp): `windows/runner/window_fx.cpp`
- [Window Chrome](https://github.com/qiannqq/elia-music-desktop/blob/Flutter/windows/runner/window_chrome.cpp): `windows/runner/window_chrome.cpp`

### Other components

- **Listener**

## Connections

- Listener → Search Page: searches (evidence: `README.md`)
- Listener → Playlist Page: imports playlists (evidence: `README.md`)
- Search Page → Music Providers: searches catalogs (evidence: `README.md`)
- Music Providers → API Client: uses API client
- Search Page → Song Model: shows results
- Playlist Page → Playlist Model: manages playlists
- Listener → Player Controller: listens (evidence: `README.md`)
- Player Controller → Local Audio Proxy: streams through (evidence: `README.md`)
- Player Controller → Lyrics Services: synchronizes lyrics (evidence: `README.md`)
- Player Controller → Audio Cache: downloads tracks (evidence: `README.md`)
- Player Controller → Now Playing: updates display
- Player Controller → Queue Panel: manages queue
- Settings Page → Local Store: configures
- Settings Page → Theme Controller: changes theme (evidence: `README.md`)
- Video Background → Now Playing: provides backdrop
- Flutter Window → SMTC Bridge: registers bridge (evidence: `windows/runner/flutter_window.cpp`)
- Flutter Window → Lyric Island: registers bridge (evidence: `windows/runner/flutter_window.cpp`)
- Flutter Window → Audio Probe Bridge: registers bridge (evidence: `windows/runner/flutter_window.cpp`)
- Flutter Window → Window Effects: registers bridge (evidence: `windows/runner/flutter_window.cpp`)
- Audio Probe Bridge → Audio Probe: invokes probe (evidence: `windows/runner/audio_probe_bridge.cpp`)
- Flutter Window → Window Chrome: uses hit testing (evidence: `windows/runner/flutter_window.cpp`)
