# xcq0607/lxserver architecture

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

- Interactive diagram: https://gitdiagram.com/xcq0607/lxserver
- Repository: https://github.com/xcq0607/lxserver

## Overview

LX Music Sync Server combines a multi-source web music player with a user/device synchronization server and management console. The main user flow is browser search or playlist selection, server-side music-source resolution, then playback or download; separately, LX Music clients connect to synchronize user lists and dislikes. The README also documents Subsonic access, custom sources, shared public collections, and WebDAV backup. The graph uses documented capabilities and sampled API interactions; unsampled route wiring is represented only where the README supports it.

Main entry points: [`src/server/server.ts`](https://github.com/xcq0607/lxserver/blob/main/src/server/server.ts) (HTTP and WebSocket Server), [`public/music/app.js`](https://github.com/xcq0607/lxserver/blob/main/public/music/app.js) (Web Player), [`src/user/index.ts`](https://github.com/xcq0607/lxserver/blob/main/src/user/index.ts) (User Data API), [`src/server/subsonic.ts`](https://github.com/xcq0607/lxserver/blob/main/src/server/subsonic.ts) (Subsonic Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Experiences"]
  node_webplayer["Web Player<br/>[app.js]"]
  node_playlist["Playlist Browser"]
  node_downloader["Download Manager"]
  node_admin["Admin Console<br/>[app.js]"]
end

subgraph group_music["Music Services"]
  node_musicapi["Music API Facade<br/>[index.js]"]
  node_providers["Music Providers"]
  node_customsource["Custom Sources<br/>[userApi.ts]"]
  node_custommusic["Custom Music Library"]
  node_filecache[("File and Lyric Cache<br/>[fileCache.ts]")]
  node_queues["Download and Remaster Queues"]
end

subgraph group_sync["Sync and Users"]
  node_userapi["User Data API<br/>[index.ts]"]
  node_listmodule["Playlist Sync<br/>[index.ts]"]
  node_dislikemodule["Dislike Sync<br/>[index.ts]"]
  node_userdata[("User Data<br/>[data.ts]")]
end

subgraph group_integration["External Interfaces"]
  node_server["HTTP and WebSocket Server<br/>[server.ts]"]
  node_webdav["WebDAV Backup<br/>[webdavSync.ts]"]
  node_subsonic["Subsonic Interface<br/>[subsonic.ts]"]
end

node_listener(("Listener"))
node_lxclient(("LX Music Client"))
node_subclient(("Subsonic Client"))
node_externalmusic(("Music Platforms"))
node_webdavservice(("WebDAV Service"))

node_listener -->|"uses"| node_webplayer
node_webplayer -->|"opens playlists"| node_playlist
node_playlist -->|"requests lists"| node_server
node_webplayer -->|"requests music"| node_server
node_downloader -->|"downloads tracks"| node_server
node_server -->|"resolves music"| node_musicapi
node_musicapi -->|"dispatches requests"| node_providers
node_providers -->|"queries platforms"| node_externalmusic
node_server -->|"loads sources"| node_customsource
node_server -->|"serves local tracks"| node_custommusic
node_server -->|"reads and writes cache"| node_filecache
node_server -->|"dispatches downloads"| node_queues
node_listener -->|"manages settings"| node_admin
node_admin -->|"calls management API"| node_server
node_lxclient -->|"connects and syncs"| node_server
node_server -->|"handles user data"| node_userapi
node_userapi -->|"manages playlists"| node_listmodule
node_userapi -->|"manages dislikes"| node_dislikemodule
node_listmodule -->|"persists user state"| node_userdata
node_dislikemodule -->|"persists user state"| node_userdata
node_server -->|"starts backups"| node_webdav
node_webdav -->|"backs up data"| node_webdavservice
node_subclient -->|"uses protocol"| node_subsonic
node_subsonic -.->|"searches online music"| node_musicapi
node_subsonic -->|"serves cached media"| node_filecache

click node_webplayer "https://github.com/xcq0607/lxserver/blob/main/public/music/app.js"
click node_playlist "https://github.com/xcq0607/lxserver/blob/main/public/music/js/songlist_manager.js"
click node_downloader "https://github.com/xcq0607/lxserver/blob/main/public/music/js/download_manager.js"
click node_admin "https://github.com/xcq0607/lxserver/blob/main/public/app.js"
click node_server "https://github.com/xcq0607/lxserver/blob/main/src/server/server.ts"
click node_musicapi "https://github.com/xcq0607/lxserver/blob/main/src/modules/utils/musicSdk/index.js"
click node_providers "https://github.com/xcq0607/lxserver/tree/main/src/modules/utils/musicSdk"
click node_customsource "https://github.com/xcq0607/lxserver/blob/main/src/server/userApi.ts"
click node_custommusic "https://github.com/xcq0607/lxserver/blob/main/src/server/customMusicManager.ts"
click node_filecache "https://github.com/xcq0607/lxserver/blob/main/src/server/fileCache.ts"
click node_queues "https://github.com/xcq0607/lxserver/blob/main/src/server/serverDownloadQueue.ts"
click node_userapi "https://github.com/xcq0607/lxserver/blob/main/src/user/index.ts"
click node_listmodule "https://github.com/xcq0607/lxserver/blob/main/src/modules/list/index.ts"
click node_dislikemodule "https://github.com/xcq0607/lxserver/blob/main/src/modules/dislike/index.ts"
click node_userdata "https://github.com/xcq0607/lxserver/blob/main/src/user/data.ts"
click node_webdav "https://github.com/xcq0607/lxserver/blob/main/src/utils/webdavSync.ts"
click node_subsonic "https://github.com/xcq0607/lxserver/blob/main/src/server/subsonic.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_webplayer,node_playlist,node_downloader,node_admin,node_lxclient,node_subclient toneBlue
class node_musicapi,node_providers,node_customsource,node_custommusic,node_filecache,node_queues toneAmber
class node_userapi,node_listmodule,node_dislikemodule,node_userdata toneMint
class node_server,node_webdav,node_subsonic toneRose
class node_listener,node_externalmusic,node_webdavservice toneIndigo
```

## Components

### Web Experiences

- [Web Player](https://github.com/xcq0607/lxserver/blob/main/public/music/app.js): `public/music/app.js`
- [Playlist Browser](https://github.com/xcq0607/lxserver/blob/main/public/music/js/songlist_manager.js): `public/music/js/songlist_manager.js`
- [Download Manager](https://github.com/xcq0607/lxserver/blob/main/public/music/js/download_manager.js): `public/music/js/download_manager.js`
- [Admin Console](https://github.com/xcq0607/lxserver/blob/main/public/app.js): `public/app.js`

### Music Services

- [Music API Facade](https://github.com/xcq0607/lxserver/blob/main/src/modules/utils/musicSdk/index.js): `src/modules/utils/musicSdk/index.js`
- [Music Providers](https://github.com/xcq0607/lxserver/tree/main/src/modules/utils/musicSdk): `src/modules/utils/musicSdk`
- [Custom Sources](https://github.com/xcq0607/lxserver/blob/main/src/server/userApi.ts): `src/server/userApi.ts`
- [Custom Music Library](https://github.com/xcq0607/lxserver/blob/main/src/server/customMusicManager.ts): `src/server/customMusicManager.ts`
- [File and Lyric Cache](https://github.com/xcq0607/lxserver/blob/main/src/server/fileCache.ts): `src/server/fileCache.ts`
- [Download and Remaster Queues](https://github.com/xcq0607/lxserver/blob/main/src/server/serverDownloadQueue.ts): `src/server/serverDownloadQueue.ts`

### Sync and Users

- [User Data API](https://github.com/xcq0607/lxserver/blob/main/src/user/index.ts): `src/user/index.ts`
- [Playlist Sync](https://github.com/xcq0607/lxserver/blob/main/src/modules/list/index.ts): `src/modules/list/index.ts`
- [Dislike Sync](https://github.com/xcq0607/lxserver/blob/main/src/modules/dislike/index.ts): `src/modules/dislike/index.ts`
- [User Data](https://github.com/xcq0607/lxserver/blob/main/src/user/data.ts): `src/user/data.ts`

### External Interfaces

- [HTTP and WebSocket Server](https://github.com/xcq0607/lxserver/blob/main/src/server/server.ts): `src/server/server.ts`
- [WebDAV Backup](https://github.com/xcq0607/lxserver/blob/main/src/utils/webdavSync.ts): `src/utils/webdavSync.ts`
- [Subsonic Interface](https://github.com/xcq0607/lxserver/blob/main/src/server/subsonic.ts): `src/server/subsonic.ts`

### Other components

- **Listener**
- **LX Music Client**
- **Subsonic Client**
- **Music Platforms**
- **WebDAV Service**

## Connections

- Listener → Web Player: uses
- Web Player → Playlist Browser: opens playlists
- Playlist Browser → HTTP and WebSocket Server: requests lists
- Web Player → HTTP and WebSocket Server: requests music
- Download Manager → HTTP and WebSocket Server: downloads tracks
- HTTP and WebSocket Server → Music API Facade: resolves music
- Music API Facade → Music Providers: dispatches requests
- Music Providers → Music Platforms: queries platforms
- HTTP and WebSocket Server → Custom Sources: loads sources
- HTTP and WebSocket Server → Custom Music Library: serves local tracks
- HTTP and WebSocket Server → File and Lyric Cache: reads and writes cache
- HTTP and WebSocket Server → Download and Remaster Queues: dispatches downloads
- Listener → Admin Console: manages settings
- Admin Console → HTTP and WebSocket Server: calls management API
- LX Music Client → HTTP and WebSocket Server: connects and syncs
- HTTP and WebSocket Server → User Data API: handles user data
- User Data API → Playlist Sync: manages playlists
- User Data API → Dislike Sync: manages dislikes
- Playlist Sync → User Data: persists user state
- Dislike Sync → User Data: persists user state
- HTTP and WebSocket Server → WebDAV Backup: starts backups
- WebDAV Backup → WebDAV Service: backs up data
- Subsonic Client → Subsonic Interface: uses protocol
- Subsonic Interface → Music API Facade: searches online music
- Subsonic Interface → File and Lyric Cache: serves cached media