# algerkong/algermusicplayer architecture

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

- Interactive diagram: https://gitdiagram.com/algerkong/algermusicplayer
- Repository: https://github.com/algerkong/algermusicplayer

## Overview

Alger Music Player is a Vue/Electron music player with desktop, web, and mobile interfaces. A typical playback journey starts in the app’s discovery views, retrieves song data through renderer APIs, and hands a selected track to the playback controller, which coordinates URL/detail loading and audio playback. Separate product branches cover lyrics, accounts and collections, local music and downloads, and desktop services. The README documents these capabilities; sampled source confirms the playback, preload bridge, download, local-file, and startup links shown here. Unsampled feature wiring is intentionally left out.

Main entry points: [`src/preload/index.ts`](https://github.com/algerkong/algermusicplayer/blob/main/src/preload/index.ts) (IPC bridge), [`src/renderer/App.vue`](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/App.vue) (App shell), [`src/renderer/services/playbackController.ts`](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/services/playbackController.ts) (Playback controller), [`src/renderer/views/search/index.vue`](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/views/search/index.vue) (Search and browse)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_app["App shell<br/>[App.vue]"]
  node_router["Routes and views<br/>[index.ts]"]
  node_settings["Settings UI<br/>[index.vue]"]
end

subgraph group_discovery["Music discovery"]
  node_search_views["Search and browse<br/>[index.vue]"]
  node_discovery_api["Catalog APIs<br/>[search.ts]"]
  node_music_api["Music API<br/>[music.ts]"]
end

subgraph group_playback["Playback and lyrics"]
  node_playback["Playback controller"]
  node_player_hooks["Track and lyric loading<br/>[usePlayerHooks.ts]"]
  node_player_state["Player state<br/>[playerCore.ts]"]
  node_audio["Audio service<br/>[audioService.ts]"]
  node_lyrics_ui["Lyrics display<br/>[MusicFull.vue]"]
end

subgraph group_library["Library and files"]
  node_account["Account and user<br/>[user.ts]"]
  node_collections["Favorites and history<br/>[favorite.ts]"]
  node_playlist["Playlist state<br/>[playlist.ts]"]
  node_local_music["Local music<br/>[localMusic.ts]"]
  node_scanner["Local scanner"]
  node_download_ui["Download controls<br/>[useDownload.ts]"]
  node_download_manager["Download manager<br/>[downloadManager.ts]"]
end

subgraph group_desktop["Desktop services"]
  node_preload["IPC bridge<br/>[index.ts]"]
  node_main["Electron main<br/>[index.ts]"]
  node_api_server["Local music API<br/>[server.ts]"]
  node_files["File and local audio<br/>[fileManager.ts]"]
  node_config[("Desktop configuration<br/>[config.ts]")]
  node_source_runner["Custom source runner"]
end

node_listener(("Listener"))
node_catalog_provider["Music catalog services"]

node_listener -->|"uses"| node_app
node_app -->|"mounts routes"| node_router
node_listener -->|"searches and browses"| node_search_views
node_search_views -->|"requests catalog"| node_discovery_api
node_discovery_api -.->|"fetches listings"| node_catalog_provider
node_search_views -->|"selects tracks"| node_playlist
node_listener -->|"starts playback"| node_playback
node_playback -->|"loads track data"| node_player_hooks
node_player_hooks -->|"resolves song and lyrics"| node_music_api
node_music_api -.->|"requests music data"| node_catalog_provider
node_playback -->|"updates playback"| node_player_state
node_playback -->|"starts audio"| node_audio
node_playback -->|"records play history"| node_collections
node_player_hooks -->|"provides lyrics"| node_lyrics_ui
node_app -->|"loads and scans"| node_local_music
node_local_music -->|"requests folder scan"| node_preload
node_preload -->|"invokes scan"| node_scanner
node_listener -->|"downloads tracks"| node_download_ui
node_download_ui -->|"sends download tasks"| node_preload
node_preload -->|"dispatches download IPC"| node_download_manager
node_app -->|"uses desktop bridge"| node_preload
node_preload -->|"sends IPC"| node_main
node_main -->|"starts local API"| node_api_server
node_main -->|"reads and saves settings"| node_config
node_preload -->|"invokes file operations"| node_files
node_listener -->|"configures app"| node_settings
node_settings -->|"updates preferences"| node_app
node_app -->|"initializes custom source"| node_source_runner

click node_app "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/App.vue"
click node_router "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/router/index.ts"
click node_settings "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/views/set/index.vue"
click node_search_views "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/views/search/index.vue"
click node_discovery_api "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/api/search.ts"
click node_music_api "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/api/music.ts"
click node_account "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/user.ts"
click node_collections "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/favorite.ts"
click node_playlist "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/playlist.ts"
click node_local_music "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/localMusic.ts"
click node_scanner "https://github.com/algerkong/algermusicplayer/blob/main/src/main/modules/localMusicScanner.ts"
click node_download_ui "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/hooks/useDownload.ts"
click node_download_manager "https://github.com/algerkong/algermusicplayer/blob/main/src/main/modules/downloadManager.ts"
click node_playback "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/services/playbackController.ts"
click node_player_hooks "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/hooks/usePlayerHooks.ts"
click node_player_state "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/playerCore.ts"
click node_audio "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/services/audioService.ts"
click node_lyrics_ui "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/components/lyric/MusicFull.vue"
click node_preload "https://github.com/algerkong/algermusicplayer/blob/main/src/preload/index.ts"
click node_main "https://github.com/algerkong/algermusicplayer/blob/main/src/main/index.ts"
click node_api_server "https://github.com/algerkong/algermusicplayer/blob/main/src/main/server.ts"
click node_files "https://github.com/algerkong/algermusicplayer/blob/main/src/main/modules/fileManager.ts"
click node_config "https://github.com/algerkong/algermusicplayer/blob/main/src/main/modules/config.ts"
click node_source_runner "https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/services/LxMusicSourceRunner.ts"

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_app,node_router,node_settings toneBlue
class node_search_views,node_discovery_api,node_music_api toneAmber
class node_playback,node_player_hooks,node_player_state,node_audio,node_lyrics_ui toneMint
class node_account,node_collections,node_playlist,node_local_music,node_scanner,node_download_ui,node_download_manager toneRose
class node_preload,node_main,node_api_server,node_files,node_config,node_source_runner,node_listener,node_catalog_provider toneIndigo
```

## Components

### App experience

- [App shell](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/App.vue): `src/renderer/App.vue`
- [Routes and views](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/router/index.ts): `src/renderer/router/index.ts`
- [Settings UI](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/views/set/index.vue): `src/renderer/views/set/index.vue`

### Music discovery

- [Search and browse](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/views/search/index.vue): `src/renderer/views/search/index.vue`
- [Catalog APIs](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/api/search.ts): `src/renderer/api/search.ts`
- [Music API](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/api/music.ts): `src/renderer/api/music.ts`

### Playback and lyrics

- [Playback controller](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/services/playbackController.ts): `src/renderer/services/playbackController.ts`
- [Track and lyric loading](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/hooks/usePlayerHooks.ts): `src/renderer/hooks/usePlayerHooks.ts`
- [Player state](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/playerCore.ts): `src/renderer/store/modules/playerCore.ts`
- [Audio service](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/services/audioService.ts): `src/renderer/services/audioService.ts`
- [Lyrics display](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/components/lyric/MusicFull.vue): `src/renderer/components/lyric/MusicFull.vue`

### Library and files

- [Account and user](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/user.ts): `src/renderer/store/modules/user.ts`
- [Favorites and history](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/favorite.ts): `src/renderer/store/modules/favorite.ts`
- [Playlist state](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/playlist.ts): `src/renderer/store/modules/playlist.ts`
- [Local music](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/store/modules/localMusic.ts): `src/renderer/store/modules/localMusic.ts`
- [Local scanner](https://github.com/algerkong/algermusicplayer/blob/main/src/main/modules/localMusicScanner.ts): `src/main/modules/localMusicScanner.ts`
- [Download controls](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/hooks/useDownload.ts): `src/renderer/hooks/useDownload.ts`
- [Download manager](https://github.com/algerkong/algermusicplayer/blob/main/src/main/modules/downloadManager.ts): `src/main/modules/downloadManager.ts`

### Desktop services

- [IPC bridge](https://github.com/algerkong/algermusicplayer/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Electron main](https://github.com/algerkong/algermusicplayer/blob/main/src/main/index.ts): `src/main/index.ts`
- [Local music API](https://github.com/algerkong/algermusicplayer/blob/main/src/main/server.ts): `src/main/server.ts`
- [File and local audio](https://github.com/algerkong/algermusicplayer/blob/main/src/main/modules/fileManager.ts): `src/main/modules/fileManager.ts`
- [Desktop configuration](https://github.com/algerkong/algermusicplayer/blob/main/src/main/modules/config.ts): `src/main/modules/config.ts`
- [Custom source runner](https://github.com/algerkong/algermusicplayer/blob/main/src/renderer/services/LxMusicSourceRunner.ts): `src/renderer/services/LxMusicSourceRunner.ts`

### Other components

- **Listener**
- **Music catalog services**

## Connections

- Listener → App shell: uses
- App shell → Routes and views: mounts routes
- Listener → Search and browse: searches and browses
- Search and browse → Catalog APIs: requests catalog
- Catalog APIs → Music catalog services: fetches listings
- Search and browse → Playlist state: selects tracks
- Listener → Playback controller: starts playback
- Playback controller → Track and lyric loading: loads track data
- Track and lyric loading → Music API: resolves song and lyrics
- Music API → Music catalog services: requests music data
- Playback controller → Player state: updates playback
- Playback controller → Audio service: starts audio
- Playback controller → Favorites and history: records play history
- Track and lyric loading → Lyrics display: provides lyrics
- App shell → Local music: loads and scans
- Local music → IPC bridge: requests folder scan
- IPC bridge → Local scanner: invokes scan
- Listener → Download controls: downloads tracks
- Download controls → IPC bridge: sends download tasks
- IPC bridge → Download manager: dispatches download IPC
- App shell → IPC bridge: uses desktop bridge
- IPC bridge → Electron main: sends IPC
- Electron main → Local music API: starts local API
- Electron main → Desktop configuration: reads and saves settings
- IPC bridge → File and local audio: invokes file operations
- Listener → Settings UI: configures app
- Settings UI → App shell: updates preferences
- App shell → Custom source runner: initializes custom source
