# streamish/music-server architecture

> Architecture diagram of the GitHub repository streamish/music-server, 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/streamish/music-server
- Repository: https://github.com/streamish/music-server

## Overview

Music Server is a self-hosted, multi-user music backend that indexes audio files and serves library data and playback through its own API and Synology AudioStation/QNAP Music Station compatibility APIs. The principal workflow is configured music folders → scheduled scanning and metadata extraction → indexed library in SQLite → client browsing, retrieval, and streaming. Admin functions manage accounts, root paths, and indexer settings; user APIs expose library and session operations. The graph uses README statements and shown source references; unsampled endpoint wiring and storage behavior are not inferred.

Main entry points: [`src/api/api.module.ts`](https://github.com/streamish/music-server/blob/main/src/api/api.module.ts) (API routing), [`src/indexer/indexer.service.ts`](https://github.com/streamish/music-server/blob/main/src/indexer/indexer.service.ts) (Indexer scheduler), [`src/app.module.ts`](https://github.com/streamish/music-server/blob/main/src/app.module.ts) (Music server), [`src/api/user/user.module.ts`](https://github.com/streamish/music-server/blob/main/src/api/user/user.module.ts) (User library API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_server["Music server<br/>[app.module.ts]"]
  node_config["Configuration<br/>[config.service.ts]"]
  node_database[("SQLite database<br/>[database.module.ts]")]
end

subgraph group_indexing["Music indexing"]
  node_indexer["Indexer scheduler<br/>[indexer.service.ts]"]
  node_albumindex["Album indexing"]
  node_associationindex["Association indexing"]
  node_trackindex["Track indexing"]
end

subgraph group_library["Library data"]
  node_library["Library queries<br/>[library.service.ts]"]
end

subgraph group_standard["Standard APIs"]
  node_accounts[("Accounts and sessions<br/>[account.entity.ts]")]
  node_authentication["Authentication"]
  node_api["API routing<br/>[api.module.ts]"]
  node_userapi["User library API<br/>[user.module.ts]"]
  node_adminapi["Admin API<br/>[admin.module.ts]"]
  node_guestapi["Guest API<br/>[guest.module.ts]"]
  node_stream["Audio streaming"]
end

subgraph group_compat["NAS compatibility"]
  node_synology["Synology API<br/>[synology.module.ts]"]
  node_synquery["Synology capabilities<br/>[query.service.ts]"]
  node_qnap["QNAP API<br/>[qnap.module.ts]"]
end

node_client(("Music clients"))
node_musicfiles["Music folders"]

node_server -->|"loads routes"| node_api
node_server -->|"loads config"| node_config
node_server -->|"loads database"| node_database
node_server -->|"loads indexer"| node_indexer
node_api -->|"registers"| node_userapi
node_api -->|"registers"| node_adminapi
node_api -->|"registers"| node_guestapi
node_api -->|"registers"| node_synology
node_api -->|"registers"| node_qnap
node_client -->|"requests"| node_api
node_musicfiles -->|"scans metadata"| node_indexer
node_indexer -->|"delegates"| node_albumindex
node_indexer -->|"delegates"| node_associationindex
node_indexer -->|"delegates"| node_trackindex
node_indexer -->|"stores index"| node_database
node_library -->|"queries entities"| node_database
node_userapi -.->|"serves library"| node_library
node_userapi -.->|"authenticates sessions"| node_authentication
node_authentication -->|"reads account data"| node_accounts
node_synology -->|"queries capabilities"| node_synquery
node_client -->|"uses compatible API"| node_synology
node_client -->|"uses compatible API"| node_qnap
node_userapi -.->|"serves audio"| node_stream
node_client -->|"streams tracks"| node_stream

click node_server "https://github.com/streamish/music-server/blob/main/src/app.module.ts"
click node_config "https://github.com/streamish/music-server/blob/main/src/config/config.service.ts"
click node_database "https://github.com/streamish/music-server/blob/main/src/database/database.module.ts"
click node_accounts "https://github.com/streamish/music-server/blob/main/src/database/entities/account.entity.ts"
click node_authentication "https://github.com/streamish/music-server/blob/main/src/authentication/authentication.service.ts"
click node_api "https://github.com/streamish/music-server/blob/main/src/api/api.module.ts"
click node_userapi "https://github.com/streamish/music-server/blob/main/src/api/user/user.module.ts"
click node_adminapi "https://github.com/streamish/music-server/blob/main/src/api/admin/admin.module.ts"
click node_guestapi "https://github.com/streamish/music-server/blob/main/src/api/guest/guest.module.ts"
click node_library "https://github.com/streamish/music-server/blob/main/src/library/library.service.ts"
click node_indexer "https://github.com/streamish/music-server/blob/main/src/indexer/indexer.service.ts"
click node_albumindex "https://github.com/streamish/music-server/blob/main/src/indexer/index-album.service.ts"
click node_associationindex "https://github.com/streamish/music-server/blob/main/src/indexer/index-association.service.ts"
click node_trackindex "https://github.com/streamish/music-server/blob/main/src/indexer/index-track.service.ts"
click node_synology "https://github.com/streamish/music-server/blob/main/src/api/synology-audiostation/synology.module.ts"
click node_synquery "https://github.com/streamish/music-server/blob/main/src/api/synology-audiostation/query.service.ts"
click node_qnap "https://github.com/streamish/music-server/blob/main/src/api/qnap-musicstation/qnap.module.ts"
click node_stream "https://github.com/streamish/music-server/blob/main/src/api/user/stream-file/stream-file.service.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_server,node_config,node_database,node_client toneBlue
class node_indexer,node_albumindex,node_associationindex,node_trackindex toneAmber
class node_library toneMint
class node_accounts,node_authentication,node_api,node_userapi,node_adminapi,node_guestapi,node_stream toneRose
class node_synology,node_synquery,node_qnap,node_musicfiles toneIndigo
```

## Components

### Server runtime

- [Music server](https://github.com/streamish/music-server/blob/main/src/app.module.ts): `src/app.module.ts`
- [Configuration](https://github.com/streamish/music-server/blob/main/src/config/config.service.ts): `src/config/config.service.ts`
- [SQLite database](https://github.com/streamish/music-server/blob/main/src/database/database.module.ts): `src/database/database.module.ts`

### Music indexing

- [Indexer scheduler](https://github.com/streamish/music-server/blob/main/src/indexer/indexer.service.ts): `src/indexer/indexer.service.ts`
- [Album indexing](https://github.com/streamish/music-server/blob/main/src/indexer/index-album.service.ts): `src/indexer/index-album.service.ts`
- [Association indexing](https://github.com/streamish/music-server/blob/main/src/indexer/index-association.service.ts): `src/indexer/index-association.service.ts`
- [Track indexing](https://github.com/streamish/music-server/blob/main/src/indexer/index-track.service.ts): `src/indexer/index-track.service.ts`

### Library data

- [Library queries](https://github.com/streamish/music-server/blob/main/src/library/library.service.ts): `src/library/library.service.ts`

### Standard APIs

- [Accounts and sessions](https://github.com/streamish/music-server/blob/main/src/database/entities/account.entity.ts): `src/database/entities/account.entity.ts`
- [Authentication](https://github.com/streamish/music-server/blob/main/src/authentication/authentication.service.ts): `src/authentication/authentication.service.ts`
- [API routing](https://github.com/streamish/music-server/blob/main/src/api/api.module.ts): `src/api/api.module.ts`
- [User library API](https://github.com/streamish/music-server/blob/main/src/api/user/user.module.ts): `src/api/user/user.module.ts`
- [Admin API](https://github.com/streamish/music-server/blob/main/src/api/admin/admin.module.ts): `src/api/admin/admin.module.ts`
- [Guest API](https://github.com/streamish/music-server/blob/main/src/api/guest/guest.module.ts): `src/api/guest/guest.module.ts`
- [Audio streaming](https://github.com/streamish/music-server/blob/main/src/api/user/stream-file/stream-file.service.ts): `src/api/user/stream-file/stream-file.service.ts`

### NAS compatibility

- [Synology API](https://github.com/streamish/music-server/blob/main/src/api/synology-audiostation/synology.module.ts): `src/api/synology-audiostation/synology.module.ts`
- [Synology capabilities](https://github.com/streamish/music-server/blob/main/src/api/synology-audiostation/query.service.ts): `src/api/synology-audiostation/query.service.ts`
- [QNAP API](https://github.com/streamish/music-server/blob/main/src/api/qnap-musicstation/qnap.module.ts): `src/api/qnap-musicstation/qnap.module.ts`

### Other components

- **Music clients**
- **Music folders**

## Connections

- Music server → API routing: loads routes (evidence: `src/app.module.ts`)
- Music server → Configuration: loads config (evidence: `src/app.module.ts`)
- Music server → SQLite database: loads database (evidence: `src/app.module.ts`)
- Music server → Indexer scheduler: loads indexer (evidence: `src/app.module.ts`)
- API routing → User library API: registers (evidence: `src/api/api.module.ts`)
- API routing → Admin API: registers (evidence: `src/api/api.module.ts`)
- API routing → Guest API: registers (evidence: `src/api/api.module.ts`)
- API routing → Synology API: registers (evidence: `src/api/api.module.ts`)
- API routing → QNAP API: registers (evidence: `src/api/api.module.ts`)
- Music clients → API routing: requests (evidence: `README.md`)
- Music folders → Indexer scheduler: scans metadata (evidence: `README.md`)
- Indexer scheduler → Album indexing: delegates (evidence: `src/indexer/indexer.service.ts`)
- Indexer scheduler → Association indexing: delegates (evidence: `src/indexer/indexer.service.ts`)
- Indexer scheduler → Track indexing: delegates (evidence: `src/indexer/indexer.service.ts`)
- Indexer scheduler → SQLite database: stores index (evidence: `README.md`)
- Library queries → SQLite database: queries entities (evidence: `src/library/library.service.ts`)
- User library API → Library queries: serves library
- User library API → Authentication: authenticates sessions
- Authentication → Accounts and sessions: reads account data (evidence: `src/authentication/authentication.service.ts`)
- Synology API → Synology capabilities: queries capabilities
- Music clients → Synology API: uses compatible API (evidence: `README.md`)
- Music clients → QNAP API: uses compatible API (evidence: `README.md`)
- User library API → Audio streaming: serves audio
- Music clients → Audio streaming: streams tracks (evidence: `README.md`)
