# naivg/bilimusic architecture

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

- Interactive diagram: https://gitdiagram.com/naivg/bilimusic
- Repository: https://github.com/naivg/bilimusic

## Overview

BiliMusic is a cross-platform Bilibili-focused audio player, with search and discovery, playlist management, playback, lyrics and themes, offline caching, and LAN device synchronization. Its documented main workflow runs from search or recommendations through playlist/queue management to playback; roaming can extend the queue, and LAN peers can synchronize playback state and control. The README also documents a separate Xiaomi Vela client. The supplied tree omits the Flutter application sources, so those product components are represented from README documentation; sampled implementation detail is limited to Vela services.

Main entry points: [`vela/src/services/playerService.js`](https://github.com/naivg/bilimusic/blob/main/vela/src/services/playerService.js) (Vela Client), [`vela/src/services/authService.js`](https://github.com/naivg/bilimusic/blob/main/vela/src/services/authService.js) (Authentication), [`vela/src/services/api.js`](https://github.com/naivg/bilimusic/blob/main/vela/src/services/api.js) (Vela API Bridge), [`vela/src/services/session.js`](https://github.com/naivg/bilimusic/blob/main/vela/src/services/session.js) (Session State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery"]
  node_app_ui["App UI"]
  node_search_recommend["Search & Recommendations"]
  node_roaming["Roaming Service"]
  node_bili_api["Bilibili API"]
end

subgraph group_playback["Playback"]
  node_player["Player Coordinator"]
  node_audio_engine["Audio Engine"]
  node_lyrics_themes["Lyrics & Themes"]
  node_audio_cache["Offline Audio Cache"]
end

subgraph group_account_data["Account & Data"]
  node_playlist["Playlists & Favorites"]
  node_local_store[("Local Data Store")]
  node_auth["Authentication<br/>[authService.js]"]
  node_session["Session State<br/>[session.js]"]
  node_vela_storage[("Vela Storage<br/>[storage.js]")]
end

subgraph group_clients["Client Integrations"]
  node_lan_sync["LAN Sync"]
  node_vela_client["Vela Client<br/>[playerService.js]"]
  node_vela_api["Vela API Bridge<br/>[api.js]"]
  node_fetch_bridge["Fetch Bridge Protocol<br/>[fetchbridge.js]"]
  node_system_audio{{"Vela Audio System"}}
  node_system_device{{"Vela Device System<br/>[deviceService.js]"}}
  node_system_app{{"Vela App System<br/>[appService.js]"}}
end

node_listener(("Listener"))
node_peer_devices(("Peer Devices"))
node_bili_service{{"Bilibili Service"}}

node_listener -->|"uses"| node_app_ui
node_app_ui -->|"requests discovery"| node_search_recommend
node_search_recommend -->|"queries"| node_bili_api
node_bili_api -->|"requests content"| node_bili_service
node_app_ui -->|"manages tracks"| node_playlist
node_playlist -->|"persists"| node_local_store
node_app_ui -->|"controls playback"| node_player
node_player -->|"drives audio"| node_audio_engine
node_player -->|"caches tracks"| node_audio_cache
node_player -->|"updates presentation"| node_lyrics_themes
node_player -.->|"requests queue additions"| node_roaming
node_roaming -->|"discovers related tracks"| node_search_recommend
node_roaming -->|"fetches candidates"| node_bili_api
node_app_ui -->|"configures sync"| node_lan_sync
node_lan_sync -->|"discovers and pairs"| node_peer_devices
node_lan_sync -->|"synchronizes playback"| node_player
node_listener -->|"uses"| node_vela_client
node_vela_client -->|"requests media"| node_vela_api
node_vela_api -->|"fetches content"| node_bili_service
node_vela_api -.->|"uses when available"| node_fetch_bridge
node_vela_client -->|"reads and writes"| node_vela_storage
node_vela_client -->|"controls audio"| node_system_audio
node_vela_client -->|"starts login"| node_auth
node_auth -->|"requests QR and profile"| node_bili_service
node_auth -->|"saves credentials"| node_session
node_session -->|"persists session"| node_vela_storage
node_vela_client -->|"reads capabilities"| node_system_device
node_vela_client -->|"reads app information"| node_system_app

click node_auth "https://github.com/naivg/bilimusic/blob/main/vela/src/services/authService.js"
click node_session "https://github.com/naivg/bilimusic/blob/main/vela/src/services/session.js"
click node_vela_storage "https://github.com/naivg/bilimusic/blob/main/vela/src/services/storage.js"
click node_vela_client "https://github.com/naivg/bilimusic/blob/main/vela/src/services/playerService.js"
click node_vela_api "https://github.com/naivg/bilimusic/blob/main/vela/src/services/api.js"
click node_fetch_bridge "https://github.com/naivg/bilimusic/blob/main/vela/src/common/fetchbridge.js"
click node_system_device "https://github.com/naivg/bilimusic/blob/main/vela/src/services/deviceService.js"
click node_system_app "https://github.com/naivg/bilimusic/blob/main/vela/src/services/appService.js"

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_ui,node_search_recommend,node_roaming,node_bili_api toneBlue
class node_player,node_audio_engine,node_lyrics_themes,node_audio_cache toneAmber
class node_playlist,node_local_store,node_auth,node_session,node_vela_storage toneMint
class node_lan_sync,node_vela_client,node_vela_api,node_fetch_bridge,node_system_audio,node_system_device,node_system_app toneRose
class node_listener,node_peer_devices,node_bili_service toneIndigo
```

## Components

### Discovery

- **App UI**
- **Search & Recommendations**
- **Roaming Service**
- **Bilibili API**

### Playback

- **Player Coordinator**
- **Audio Engine**
- **Lyrics & Themes**
- **Offline Audio Cache**

### Account & Data

- **Playlists & Favorites**
- **Local Data Store**
- [Authentication](https://github.com/naivg/bilimusic/blob/main/vela/src/services/authService.js): `vela/src/services/authService.js`
- [Session State](https://github.com/naivg/bilimusic/blob/main/vela/src/services/session.js): `vela/src/services/session.js`
- [Vela Storage](https://github.com/naivg/bilimusic/blob/main/vela/src/services/storage.js): `vela/src/services/storage.js`

### Client Integrations

- **LAN Sync**
- [Vela Client](https://github.com/naivg/bilimusic/blob/main/vela/src/services/playerService.js): `vela/src/services/playerService.js`
- [Vela API Bridge](https://github.com/naivg/bilimusic/blob/main/vela/src/services/api.js): `vela/src/services/api.js`
- [Fetch Bridge Protocol](https://github.com/naivg/bilimusic/blob/main/vela/src/common/fetchbridge.js): `vela/src/common/fetchbridge.js`
- **Vela Audio System**
- [Vela Device System](https://github.com/naivg/bilimusic/blob/main/vela/src/services/deviceService.js): `vela/src/services/deviceService.js`
- [Vela App System](https://github.com/naivg/bilimusic/blob/main/vela/src/services/appService.js): `vela/src/services/appService.js`

### Other components

- **Listener**
- **Peer Devices**
- **Bilibili Service**

## Connections

- Listener → App UI: uses
- App UI → Search & Recommendations: requests discovery
- Search & Recommendations → Bilibili API: queries
- Bilibili API → Bilibili Service: requests content
- App UI → Playlists & Favorites: manages tracks
- Playlists & Favorites → Local Data Store: persists
- App UI → Player Coordinator: controls playback
- Player Coordinator → Audio Engine: drives audio
- Player Coordinator → Offline Audio Cache: caches tracks
- Player Coordinator → Lyrics & Themes: updates presentation
- Player Coordinator → Roaming Service: requests queue additions
- Roaming Service → Search & Recommendations: discovers related tracks
- Roaming Service → Bilibili API: fetches candidates
- App UI → LAN Sync: configures sync
- LAN Sync → Peer Devices: discovers and pairs
- LAN Sync → Player Coordinator: synchronizes playback
- Listener → Vela Client: uses
- Vela Client → Vela API Bridge: requests media
- Vela API Bridge → Bilibili Service: fetches content
- Vela API Bridge → Fetch Bridge Protocol: uses when available
- Vela Client → Vela Storage: reads and writes
- Vela Client → Vela Audio System: controls audio
- Vela Client → Authentication: starts login
- Authentication → Bilibili Service: requests QR and profile
- Authentication → Session State: saves credentials
- Session State → Vela Storage: persists session
- Vela Client → Vela Device System: reads capabilities
- Vela Client → Vela App System: reads app information