# nb-group/nb_music architecture

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

- Interactive diagram: https://gitdiagram.com/nb-group/nb_music
- Repository: https://github.com/nb-group/nb_music

## Overview

NB Music is an Electron-based cross-platform music player: users search and import music, manage playlists, then play audio with synchronized lyrics and optional video. The repository also includes a Flask service for Bilibili-backed login, playlists, and music mappings. The desktop flow and Bilibili favorites import are supported by excerpts and the README; other module wiring is included only where the SOURCE INDEX names the relationship. The backend’s routes and file-backed persistence are shown in excerpts, but the frontend-to-backend API wiring was not sampled.

Main entry points: [`src/script.js`](https://github.com/nb-group/nb_music/blob/main/src/script.js) (App Bootstrap), [`src/javascript/PlaylistManager.js`](https://github.com/nb-group/nb_music/blob/main/src/javascript/PlaylistManager.js) (Playlist & Queue), [`src/javascript/UIManager.js`](https://github.com/nb-group/nb_music/blob/main/src/javascript/UIManager.js) (Interface), [`src/javascript/AudioPlayer.js`](https://github.com/nb-group/nb_music/blob/main/src/javascript/AudioPlayer.js) (Audio Player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop App"]
  node_bootstrap["App Bootstrap<br/>[script.js]"]
  node_ui["Interface<br/>[UIManager.js]"]
  node_settings["Settings<br/>[SettingManager.js]"]
end

subgraph group_discovery["Music Discovery"]
  node_search["Music Search<br/>[MusicSearcher.js]"]
  node_bili{{"Bilibili API"}}
  node_netease{{"NetEase API"}}
  node_imports["Favorites Import"]
  node_cache["URL Cache<br/>[CacheManager.js]"]
end

subgraph group_playback["Playback"]
  node_playlist["Playlist &amp; Queue<br/>[PlaylistManager.js]"]
  node_audio["Audio Player<br/>[AudioPlayer.js]"]
  node_lyrics["Lyrics Player<br/>[LyricsPlayer.js]"]
  node_video["Video Player"]
  node_effects["Audio Effects<br/>[EffectManager.js]"]
end

subgraph group_account["Personal Library"]
  node_favorites["Favorites<br/>[FavoriteManager.js]"]
  node_local["Local Import"]
  node_login["Account Login<br/>[LoginManager.js]"]
  node_localstore[("Browser Storage")]
end

subgraph group_service["Backend Service"]
  node_server["Flask App<br/>[app.py]"]
  node_authroute["Login Routes<br/>[auth_routes.py]"]
  node_auth["Session Auth<br/>[auth.py]"]
  node_playroutes["Playlist Routes<br/>[playlist_routes.py]"]
  node_maproutes["Mapping Routes<br/>[mapping_routes.py]"]
  node_playservice["Playback Routes<br/>[play_routes.py]"]
  node_storage[("JSON Storage<br/>[file_storage.py]")]
end

node_user(("Listener"))
node_biliuser{{"Bilibili Service"}}

node_user -->|"operates"| node_ui
node_bootstrap -->|"initializes"| node_search
node_bootstrap -->|"initializes"| node_playlist
node_bootstrap -->|"initializes"| node_audio
node_bootstrap -->|"initializes"| node_ui
node_bootstrap -->|"initializes"| node_settings
node_bootstrap -->|"initializes"| node_imports
node_bootstrap -->|"initializes"| node_favorites
node_bootstrap -->|"initializes"| node_local
node_bootstrap -->|"initializes"| node_login
node_bootstrap -->|"initializes"| node_video
node_bootstrap -->|"initializes"| node_effects
node_ui -->|"controls"| node_playlist
node_ui -->|"fetches lyrics"| node_search
node_ui -->|"reads settings"| node_settings
node_search -->|"searches media"| node_bili
node_search -->|"fetches lyrics"| node_netease
node_imports -->|"imports favorites"| node_bili
node_imports -->|"adds playlists"| node_playlist
node_playlist -->|"gets audio links"| node_search
node_playlist -.->|"caches URLs"| node_cache
node_playlist -->|"sets audio source"| node_audio
node_playlist -->|"saves progress"| node_localstore
node_audio -->|"requests retry"| node_playlist
node_audio -->|"syncs playback"| node_lyrics
node_audio -.->|"syncs progress"| node_video
node_effects -->|"processes audio"| node_audio
node_effects -->|"reads settings"| node_settings
node_favorites -->|"selects songs"| node_playlist
node_favorites -->|"refreshes display"| node_ui
node_favorites -.->|"persists favorites"| node_localstore
node_settings -->|"stores configuration"| node_localstore
node_video -->|"gets video URL"| node_playlist
node_login -->|"updates interface"| node_ui
node_login -.->|"authenticates"| node_biliuser
node_server -->|"registers routes"| node_authroute
node_server -->|"registers routes"| node_playroutes
node_server -->|"registers routes"| node_maproutes
node_server -->|"registers routes"| node_playservice
node_authroute -->|"verifies identity"| node_biliuser
node_authroute -->|"creates session"| node_auth
node_authroute -->|"stores sessions"| node_storage
node_auth -->|"loads sessions"| node_storage
node_playroutes -->|"checks access"| node_auth
node_playroutes -->|"reads and writes"| node_storage
node_maproutes -->|"checks access"| node_auth
node_maproutes -->|"reads and writes"| node_storage
node_playservice -->|"checks access"| node_auth

click node_bootstrap "https://github.com/nb-group/nb_music/blob/main/src/script.js"
click node_ui "https://github.com/nb-group/nb_music/blob/main/src/javascript/UIManager.js"
click node_settings "https://github.com/nb-group/nb_music/blob/main/src/javascript/SettingManager.js"
click node_search "https://github.com/nb-group/nb_music/blob/main/src/javascript/MusicSearcher.js"
click node_imports "https://github.com/nb-group/nb_music/blob/main/src/javascript/MusiclistManager.js"
click node_cache "https://github.com/nb-group/nb_music/blob/main/src/javascript/CacheManager.js"
click node_playlist "https://github.com/nb-group/nb_music/blob/main/src/javascript/PlaylistManager.js"
click node_audio "https://github.com/nb-group/nb_music/blob/main/src/javascript/AudioPlayer.js"
click node_lyrics "https://github.com/nb-group/nb_music/blob/main/src/javascript/LyricsPlayer.js"
click node_video "https://github.com/nb-group/nb_music/blob/main/src/javascript/VideoPlayerManager.js"
click node_effects "https://github.com/nb-group/nb_music/blob/main/src/javascript/EffectManager.js"
click node_favorites "https://github.com/nb-group/nb_music/blob/main/src/javascript/FavoriteManager.js"
click node_local "https://github.com/nb-group/nb_music/blob/main/src/javascript/LocalImportManager.js"
click node_login "https://github.com/nb-group/nb_music/blob/main/src/javascript/LoginManager.js"
click node_server "https://github.com/nb-group/nb_music/blob/main/server/app.py"
click node_authroute "https://github.com/nb-group/nb_music/blob/main/server/routes/auth_routes.py"
click node_auth "https://github.com/nb-group/nb_music/blob/main/server/utils/auth.py"
click node_playroutes "https://github.com/nb-group/nb_music/blob/main/server/routes/playlist_routes.py"
click node_maproutes "https://github.com/nb-group/nb_music/blob/main/server/routes/mapping_routes.py"
click node_playservice "https://github.com/nb-group/nb_music/blob/main/server/routes/play_routes.py"
click node_storage "https://github.com/nb-group/nb_music/blob/main/server/utils/file_storage.py"

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_bootstrap,node_ui,node_settings toneBlue
class node_search,node_bili,node_netease,node_imports,node_cache toneAmber
class node_playlist,node_audio,node_lyrics,node_video,node_effects toneMint
class node_favorites,node_local,node_login,node_localstore toneRose
class node_server,node_authroute,node_auth,node_playroutes,node_maproutes,node_playservice,node_storage,node_user,node_biliuser toneIndigo
```

## Components

### Desktop App

- [App Bootstrap](https://github.com/nb-group/nb_music/blob/main/src/script.js): `src/script.js`
- [Interface](https://github.com/nb-group/nb_music/blob/main/src/javascript/UIManager.js): `src/javascript/UIManager.js`
- [Settings](https://github.com/nb-group/nb_music/blob/main/src/javascript/SettingManager.js): `src/javascript/SettingManager.js`

### Music Discovery

- [Music Search](https://github.com/nb-group/nb_music/blob/main/src/javascript/MusicSearcher.js): `src/javascript/MusicSearcher.js`
- **Bilibili API**
- **NetEase API**
- [Favorites Import](https://github.com/nb-group/nb_music/blob/main/src/javascript/MusiclistManager.js): `src/javascript/MusiclistManager.js`
- [URL Cache](https://github.com/nb-group/nb_music/blob/main/src/javascript/CacheManager.js): `src/javascript/CacheManager.js`

### Playback

- [Playlist & Queue](https://github.com/nb-group/nb_music/blob/main/src/javascript/PlaylistManager.js): `src/javascript/PlaylistManager.js`
- [Audio Player](https://github.com/nb-group/nb_music/blob/main/src/javascript/AudioPlayer.js): `src/javascript/AudioPlayer.js`
- [Lyrics Player](https://github.com/nb-group/nb_music/blob/main/src/javascript/LyricsPlayer.js): `src/javascript/LyricsPlayer.js`
- [Video Player](https://github.com/nb-group/nb_music/blob/main/src/javascript/VideoPlayerManager.js): `src/javascript/VideoPlayerManager.js`
- [Audio Effects](https://github.com/nb-group/nb_music/blob/main/src/javascript/EffectManager.js): `src/javascript/EffectManager.js`

### Personal Library

- [Favorites](https://github.com/nb-group/nb_music/blob/main/src/javascript/FavoriteManager.js): `src/javascript/FavoriteManager.js`
- [Local Import](https://github.com/nb-group/nb_music/blob/main/src/javascript/LocalImportManager.js): `src/javascript/LocalImportManager.js`
- [Account Login](https://github.com/nb-group/nb_music/blob/main/src/javascript/LoginManager.js): `src/javascript/LoginManager.js`
- **Browser Storage**

### Backend Service

- [Flask App](https://github.com/nb-group/nb_music/blob/main/server/app.py): `server/app.py`
- [Login Routes](https://github.com/nb-group/nb_music/blob/main/server/routes/auth_routes.py): `server/routes/auth_routes.py`
- [Session Auth](https://github.com/nb-group/nb_music/blob/main/server/utils/auth.py): `server/utils/auth.py`
- [Playlist Routes](https://github.com/nb-group/nb_music/blob/main/server/routes/playlist_routes.py): `server/routes/playlist_routes.py`
- [Mapping Routes](https://github.com/nb-group/nb_music/blob/main/server/routes/mapping_routes.py): `server/routes/mapping_routes.py`
- [Playback Routes](https://github.com/nb-group/nb_music/blob/main/server/routes/play_routes.py): `server/routes/play_routes.py`
- [JSON Storage](https://github.com/nb-group/nb_music/blob/main/server/utils/file_storage.py): `server/utils/file_storage.py`

### Other components

- **Listener**
- **Bilibili Service**

## Connections

- Listener → Interface: operates (evidence: `README.md`)
- App Bootstrap → Music Search: initializes (evidence: `src/script.js`)
- App Bootstrap → Playlist & Queue: initializes (evidence: `src/script.js`)
- App Bootstrap → Audio Player: initializes (evidence: `src/script.js`)
- App Bootstrap → Interface: initializes (evidence: `src/script.js`)
- App Bootstrap → Settings: initializes (evidence: `src/script.js`)
- App Bootstrap → Favorites Import: initializes (evidence: `src/script.js`)
- App Bootstrap → Favorites: initializes (evidence: `src/script.js`)
- App Bootstrap → Local Import: initializes (evidence: `src/script.js`)
- App Bootstrap → Account Login: initializes (evidence: `src/script.js`)
- App Bootstrap → Video Player: initializes (evidence: `src/script.js`)
- App Bootstrap → Audio Effects: initializes (evidence: `src/script.js`)
- Interface → Playlist & Queue: controls (evidence: `src/javascript/UIManager.js`)
- Interface → Music Search: fetches lyrics (evidence: `src/javascript/UIManager.js`)
- Interface → Settings: reads settings (evidence: `src/javascript/UIManager.js`)
- Music Search → Bilibili API: searches media (evidence: `README.md`)
- Music Search → NetEase API: fetches lyrics (evidence: `README.md`)
- Favorites Import → Bilibili API: imports favorites (evidence: `src/javascript/MusiclistManager.js`)
- Favorites Import → Playlist & Queue: adds playlists (evidence: `src/javascript/MusiclistManager.js`)
- Playlist & Queue → Music Search: gets audio links (evidence: `src/javascript/PlaylistManager.js`)
- Playlist & Queue → URL Cache: caches URLs (evidence: `README.md`)
- Playlist & Queue → Audio Player: sets audio source (evidence: `src/javascript/PlaylistManager.js`)
- Playlist & Queue → Browser Storage: saves progress (evidence: `README.md`)
- Audio Player → Playlist & Queue: requests retry (evidence: `src/javascript/AudioPlayer.js`)
- Audio Player → Lyrics Player: syncs playback (evidence: `README.md`)
- Audio Player → Video Player: syncs progress (evidence: `README.md`)
- Audio Effects → Audio Player: processes audio (evidence: `src/javascript/EffectManager.js`)
- Audio Effects → Settings: reads settings (evidence: `src/javascript/EffectManager.js`)
- Favorites → Playlist & Queue: selects songs (evidence: `src/javascript/FavoriteManager.js`)
- Favorites → Interface: refreshes display (evidence: `src/javascript/FavoriteManager.js`)
- Favorites → Browser Storage: persists favorites (evidence: `README.md`)
- Settings → Browser Storage: stores configuration (evidence: `README.md`)
- Video Player → Playlist & Queue: gets video URL (evidence: `src/javascript/VideoPlayerManager.js`)
- Account Login → Interface: updates interface (evidence: `src/javascript/LoginManager.js`)
- Account Login → Bilibili Service: authenticates
- Flask App → Login Routes: registers routes (evidence: `server/app.py`)
- Flask App → Playlist Routes: registers routes (evidence: `server/app.py`)
- Flask App → Mapping Routes: registers routes (evidence: `server/app.py`)
- Flask App → Playback Routes: registers routes (evidence: `server/app.py`)
- Login Routes → Bilibili Service: verifies identity (evidence: `server/routes/auth_routes.py`)
- Login Routes → Session Auth: creates session (evidence: `server/routes/auth_routes.py`)
- Login Routes → JSON Storage: stores sessions (evidence: `server/routes/auth_routes.py`)
- Session Auth → JSON Storage: loads sessions (evidence: `server/utils/auth.py`)
- Playlist Routes → Session Auth: checks access (evidence: `server/routes/playlist_routes.py`)
- Playlist Routes → JSON Storage: reads and writes (evidence: `server/routes/playlist_routes.py`)
- Mapping Routes → Session Auth: checks access (evidence: `server/routes/mapping_routes.py`)
- Mapping Routes → JSON Storage: reads and writes (evidence: `server/routes/mapping_routes.py`)
- Playback Routes → Session Auth: checks access (evidence: `server/routes/play_routes.py`)
