# music-assistant/server architecture

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

- Interactive diagram: https://gitdiagram.com/music-assistant/server
- Repository: https://github.com/music-assistant/server

## Overview

Music Assistant is a server-side media library manager that connects streaming services with networked speakers. The principal workflow is selecting catalog media for a player, resolving it into a queue, streaming audio, and delivering it to a speaker. The graph also preserves major supporting capabilities such as metadata, recommendations, discovery, storage, and authenticated API access. Relationships beyond those stated in the README are limited: sampled files and the SOURCE INDEX show some module references, but not enough runtime wiring to verify a complete call chain.

Main entry points: [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/dev/music_assistant/mass.py) (Server runtime), [`music_assistant/controllers/music/controller.py`](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/music/controller.py) (Music library), [`music_assistant/controllers/players/controller.py`](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/players/controller.py) (Player control), [`music_assistant/controllers/player_queues/controller.py`](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/player_queues/controller.py) (Player queues)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server Core"]
  node_server["Server runtime<br/>[mass.py]"]
  node_core_controller["Core controllers<br/>[core_controller.py]"]
  node_tasks["Background tasks<br/>[context.py]"]
end

subgraph group_catalog["Music Catalog"]
  node_music[("Music library<br/>[controller.py]")]
  node_media["Media item model<br/>[base.py]"]
  node_metadata["Metadata enrichment<br/>[controller.py]"]
  node_recommendations["Recommendations<br/>[controller.py]"]
end

subgraph group_playback["Playback"]
  node_queue["Player queues<br/>[controller.py]"]
  node_streams["Audio streaming<br/>[controller.py]"]
  node_players["Player control<br/>[controller.py]"]
  node_player_model["Player state model<br/>[player.py]"]
end

subgraph group_providers["Provider Integrations"]
  node_music_provider["Music provider contract<br/>[music_provider.py]"]
  node_player_provider["Player provider contract<br/>[player_provider.py]"]
  node_providers["Service integrations"]
end

subgraph group_platform["Access and Platform"]
  node_web["Web API<br/>[controller.py]"]
  node_auth["Request authentication<br/>[auth_middleware.py]"]
  node_discovery["Device discovery<br/>[controller.py]"]
  node_storage["Storage management<br/>[controller.py]"]
  node_config["Configuration<br/>[controller.py]"]
end

node_operator(("Music user"))
node_speakers(("Connected speakers"))
node_services(("Streaming services"))

node_operator -->|"uses"| node_server
node_server -->|"connects services"| node_services
node_server -->|"connects speakers"| node_speakers
node_server -.->|"hosts controllers"| node_core_controller
node_web -->|"authenticates requests"| node_auth
node_music -->|"manages media"| node_media
node_music -->|"uses enrichment"| node_metadata
node_music -.->|"offers recommendations"| node_recommendations
node_queue -->|"lists media"| node_music
node_players -->|"manages player state"| node_player_model
node_players -->|"uses provider contract"| node_player_provider
node_music_provider -.->|"supplies catalog items"| node_music
node_providers -.->|"implements contract"| node_music_provider
node_providers -.->|"implements contract"| node_player_provider
node_queue -.->|"resolves audio"| node_streams
node_streams -.->|"delivers audio"| node_players
node_server -.->|"schedules work"| node_tasks
node_server -.->|"provides discovery"| node_discovery
node_server -.->|"provides storage"| node_storage
node_server -.->|"provides configuration"| node_config

click node_server "https://github.com/music-assistant/server/blob/dev/music_assistant/mass.py"
click node_core_controller "https://github.com/music-assistant/server/blob/dev/music_assistant/models/core_controller.py"
click node_tasks "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/tasks/context.py"
click node_web "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/webserver/controller.py"
click node_auth "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/webserver/helpers/auth_middleware.py"
click node_music "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/music/controller.py"
click node_media "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/music/media/base.py"
click node_metadata "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/metadata/controller.py"
click node_recommendations "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/music/recommendations/controller.py"
click node_queue "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/player_queues/controller.py"
click node_streams "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/streams/controller.py"
click node_players "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/players/controller.py"
click node_player_model "https://github.com/music-assistant/server/blob/dev/music_assistant/models/player.py"
click node_music_provider "https://github.com/music-assistant/server/blob/dev/music_assistant/models/music_provider.py"
click node_player_provider "https://github.com/music-assistant/server/blob/dev/music_assistant/models/player_provider.py"
click node_providers "https://github.com/music-assistant/server/tree/dev/music_assistant/providers"
click node_discovery "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/discovery/controller.py"
click node_storage "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/storage/controller.py"
click node_config "https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/config/controller.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_server,node_core_controller,node_tasks,node_operator toneBlue
class node_music,node_media,node_metadata,node_recommendations toneAmber
class node_queue,node_streams,node_players,node_player_model toneMint
class node_music_provider,node_player_provider,node_providers toneRose
class node_web,node_auth,node_discovery,node_storage,node_config,node_speakers,node_services toneIndigo
```

## Components

### Server Core

- [Server runtime](https://github.com/music-assistant/server/blob/dev/music_assistant/mass.py): `music_assistant/mass.py`
- [Core controllers](https://github.com/music-assistant/server/blob/dev/music_assistant/models/core_controller.py): `music_assistant/models/core_controller.py`
- [Background tasks](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/tasks/context.py): `music_assistant/controllers/tasks/context.py`

### Music Catalog

- [Music library](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/music/controller.py): `music_assistant/controllers/music/controller.py`
- [Media item model](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/music/media/base.py): `music_assistant/controllers/music/media/base.py`
- [Metadata enrichment](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/metadata/controller.py): `music_assistant/controllers/metadata/controller.py`
- [Recommendations](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/music/recommendations/controller.py): `music_assistant/controllers/music/recommendations/controller.py`

### Playback

- [Player queues](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/player_queues/controller.py): `music_assistant/controllers/player_queues/controller.py`
- [Audio streaming](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/streams/controller.py): `music_assistant/controllers/streams/controller.py`
- [Player control](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/players/controller.py): `music_assistant/controllers/players/controller.py`
- [Player state model](https://github.com/music-assistant/server/blob/dev/music_assistant/models/player.py): `music_assistant/models/player.py`

### Provider Integrations

- [Music provider contract](https://github.com/music-assistant/server/blob/dev/music_assistant/models/music_provider.py): `music_assistant/models/music_provider.py`
- [Player provider contract](https://github.com/music-assistant/server/blob/dev/music_assistant/models/player_provider.py): `music_assistant/models/player_provider.py`
- [Service integrations](https://github.com/music-assistant/server/tree/dev/music_assistant/providers): `music_assistant/providers`

### Access and Platform

- [Web API](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/webserver/controller.py): `music_assistant/controllers/webserver/controller.py`
- [Request authentication](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/webserver/helpers/auth_middleware.py): `music_assistant/controllers/webserver/helpers/auth_middleware.py`
- [Device discovery](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/discovery/controller.py): `music_assistant/controllers/discovery/controller.py`
- [Storage management](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/storage/controller.py): `music_assistant/controllers/storage/controller.py`
- [Configuration](https://github.com/music-assistant/server/blob/dev/music_assistant/controllers/config/controller.py): `music_assistant/controllers/config/controller.py`

### Other components

- **Music user**
- **Connected speakers**
- **Streaming services**

## Connections

- Music user → Server runtime: uses
- Server runtime → Streaming services: connects services
- Server runtime → Connected speakers: connects speakers
- Server runtime → Core controllers: hosts controllers (evidence: `music_assistant/mass.py`)
- Web API → Request authentication: authenticates requests (evidence: `music_assistant/controllers/webserver/controller.py`)
- Music library → Media item model: manages media (evidence: `music_assistant/controllers/music/controller.py`)
- Music library → Metadata enrichment: uses enrichment (evidence: `music_assistant/controllers/metadata/controller.py`)
- Music library → Recommendations: offers recommendations (evidence: `music_assistant/controllers/music/controller.py`)
- Player queues → Music library: lists media (evidence: `music_assistant/controllers/player_queues/controller.py`)
- Player control → Player state model: manages player state (evidence: `music_assistant/controllers/players/controller.py`)
- Player control → Player provider contract: uses provider contract (evidence: `music_assistant/controllers/players/controller.py`)
- Music provider contract → Music library: supplies catalog items (evidence: `music_assistant/controllers/music/controller.py`)
- Service integrations → Music provider contract: implements contract (evidence: `music_assistant/providers/nicovideo/services/manager.py`)
- Service integrations → Player provider contract: implements contract (evidence: `music_assistant/providers/sendspin/bridge_manager.py`)
- Player queues → Audio streaming: resolves audio
- Audio streaming → Player control: delivers audio
- Server runtime → Background tasks: schedules work
- Server runtime → Device discovery: provides discovery
- Server runtime → Storage management: provides storage (evidence: `music_assistant/controllers/storage/controller.py`)
- Server runtime → Configuration: provides configuration
