# metabrainz/listenbrainz-server architecture

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

- Interactive diagram: https://gitdiagram.com/metabrainz/listenbrainz-server
- Repository: https://github.com/metabrainz/listenbrainz-server

## Overview

ListenBrainz records listening activity and turns it into personal and community-facing insights, recommendations, and open data. The main user flow is submitting listens, storing them, computing statistics, and presenting dashboards and year-in-music views. Other major capabilities include music-service connections and imports, playlist and recommendation features, Labs metadata APIs, and data dumps. The graph follows only relationships shown in the supplied excerpts, README, or SOURCE INDEX; several indexed core modules are absent from the supplied tree, so their implementations and links are not inferred.

Main entry points: [`frontend/js/src/user/routes/userRoutes.tsx`](https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/user/routes/userRoutes.tsx) (User routes), [`listenbrainz_spark/stats/incremental/incremental_stats_engine.py`](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/stats/incremental/incremental_stats_engine.py) (Incremental stats), [`listenbrainz/webserver/__init__.py`](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/webserver/__init__.py) (ListenBrainz web app), [`frontend/js/src/routes/routes.tsx`](https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/routes/routes.tsx) (Frontend routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["ListenBrainz web app<br/>[__init__.py]"]
  node_routes["Frontend routes<br/>[routes.tsx]"]
  node_user_routes["User routes<br/>[userRoutes.tsx]"]
  node_dashboard["Listening dashboard<br/>[Dashboard.tsx]"]
  node_year_music["Year in Music<br/>[YearInMusic.tsx]"]
end

subgraph group_listening["Listening data"]
  node_api["Listen API<br/>[api.py]"]
  node_listenstore[("Listen storage")]
  node_timescale[("Timescale access<br/>[timescale.py]")]
  node_importers["Listen importers"]
end

subgraph group_insights["Insights and discovery"]
  node_stats_engine["Incremental stats"]
  node_listen_data["Spark listen data<br/>[data.py]"]
  node_query_map["Spark query dispatch<br/>[query_map.py]"]
  node_spark_handlers["Spark result handlers<br/>[handlers.py]"]
  node_spark_results["Popularity analytics<br/>[main.py]"]
end

subgraph group_services["Integrations and data"]
  node_service_links["Music-service links"]
  node_oauth_store[("OAuth records")]
  node_labs["Labs metadata APIs<br/>[main.py]"]
  node_dump_manager["Dump management<br/>[manager.py]"]
  node_dump_store[("Dump listen store")]
end

node_listener(("Listener"))

node_listener -.->|"uses"| node_webapp
node_webapp -.->|"serves experience"| node_routes
node_routes -->|"routes users"| node_user_routes
node_user_routes -->|"loads dashboard"| node_dashboard
node_user_routes -->|"loads year views"| node_year_music
node_listener -.->|"submits listens"| node_api
node_api -.->|"writes listens"| node_listenstore
node_importers -.->|"imports listens"| node_listenstore
node_service_links -->|"uses OAuth records"| node_oauth_store
node_stats_engine -->|"loads listen data"| node_listen_data
node_stats_engine -->|"computes aggregates"| node_spark_results
node_query_map -->|"dispatches queries"| node_spark_results
node_spark_handlers -.->|"stores user stats"| node_dashboard
node_dump_manager -->|"creates listen dumps"| node_dump_store
node_listener -.->|"queries metadata"| node_labs

click node_webapp "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/webserver/__init__.py"
click node_routes "https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/routes/routes.tsx"
click node_user_routes "https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/user/routes/userRoutes.tsx"
click node_dashboard "https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/user/Dashboard.tsx"
click node_year_music "https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/user/year-in-music/YearInMusic.tsx"
click node_api "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/webserver/views/api.py"
click node_listenstore "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/listenstore/timescale_listenstore.py"
click node_timescale "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/db/timescale.py"
click node_importers "https://github.com/metabrainz/listenbrainz-server/tree/master/listenbrainz/background/listens_importer"
click node_service_links "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/domain/external_service.py"
click node_oauth_store "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/db/external_service_oauth.py"
click node_stats_engine "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/stats/incremental/incremental_stats_engine.py"
click node_listen_data "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/listens/data.py"
click node_query_map "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/query_map.py"
click node_spark_handlers "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/spark/handlers.py"
click node_labs "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/labs_api/labs/main.py"
click node_dump_manager "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/dumps/manager.py"
click node_dump_store "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/listenstore/dump_listenstore.py"
click node_spark_results "https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/popularity/main.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_webapp,node_routes,node_user_routes,node_dashboard,node_year_music toneBlue
class node_api,node_listenstore,node_timescale,node_importers toneAmber
class node_stats_engine,node_listen_data,node_query_map,node_spark_handlers,node_spark_results toneMint
class node_service_links,node_oauth_store,node_labs,node_dump_manager,node_dump_store toneRose
class node_listener toneIndigo
```

## Components

### Web experience

- [ListenBrainz web app](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/webserver/__init__.py): `listenbrainz/webserver/__init__.py`
- [Frontend routes](https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/routes/routes.tsx): `frontend/js/src/routes/routes.tsx`
- [User routes](https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/user/routes/userRoutes.tsx): `frontend/js/src/user/routes/userRoutes.tsx`
- [Listening dashboard](https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/user/Dashboard.tsx): `frontend/js/src/user/Dashboard.tsx`
- [Year in Music](https://github.com/metabrainz/listenbrainz-server/blob/master/frontend/js/src/user/year-in-music/YearInMusic.tsx): `frontend/js/src/user/year-in-music/YearInMusic.tsx`

### Listening data

- [Listen API](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/webserver/views/api.py): `listenbrainz/webserver/views/api.py`
- [Listen storage](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/listenstore/timescale_listenstore.py): `listenbrainz/listenstore/timescale_listenstore.py`
- [Timescale access](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/db/timescale.py): `listenbrainz/db/timescale.py`
- [Listen importers](https://github.com/metabrainz/listenbrainz-server/tree/master/listenbrainz/background/listens_importer): `listenbrainz/background/listens_importer`

### Insights and discovery

- [Incremental stats](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/stats/incremental/incremental_stats_engine.py): `listenbrainz_spark/stats/incremental/incremental_stats_engine.py`
- [Spark listen data](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/listens/data.py): `listenbrainz_spark/listens/data.py`
- [Spark query dispatch](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/query_map.py): `listenbrainz_spark/query_map.py`
- [Spark result handlers](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/spark/handlers.py): `listenbrainz/spark/handlers.py`
- [Popularity analytics](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz_spark/popularity/main.py): `listenbrainz_spark/popularity/main.py`

### Integrations and data

- [Music-service links](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/domain/external_service.py): `listenbrainz/domain/external_service.py`
- [OAuth records](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/db/external_service_oauth.py): `listenbrainz/db/external_service_oauth.py`
- [Labs metadata APIs](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/labs_api/labs/main.py): `listenbrainz/labs_api/labs/main.py`
- [Dump management](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/dumps/manager.py): `listenbrainz/dumps/manager.py`
- [Dump listen store](https://github.com/metabrainz/listenbrainz-server/blob/master/listenbrainz/listenstore/dump_listenstore.py): `listenbrainz/listenstore/dump_listenstore.py`

### Other components

- **Listener**

## Connections

- Listener → ListenBrainz web app: uses
- ListenBrainz web app → Frontend routes: serves experience
- Frontend routes → User routes: routes users (evidence: `frontend/js/src/routes/routes.tsx`)
- User routes → Listening dashboard: loads dashboard (evidence: `frontend/js/src/user/routes/userRoutes.tsx`)
- User routes → Year in Music: loads year views (evidence: `frontend/js/src/user/routes/userRoutes.tsx`)
- Listener → Listen API: submits listens
- Listen API → Listen storage: writes listens
- Listen importers → Listen storage: imports listens
- Music-service links → OAuth records: uses OAuth records (evidence: `listenbrainz/domain/external_service.py`)
- Incremental stats → Spark listen data: loads listen data (evidence: `listenbrainz_spark/stats/incremental/incremental_stats_engine.py`)
- Incremental stats → Popularity analytics: computes aggregates (evidence: `listenbrainz_spark/popularity/main.py`)
- Spark query dispatch → Popularity analytics: dispatches queries (evidence: `listenbrainz_spark/query_map.py`)
- Spark result handlers → Listening dashboard: stores user stats
- Dump management → Dump listen store: creates listen dumps (evidence: `listenbrainz/dumps/manager.py`)
- Listener → Labs metadata APIs: queries metadata (evidence: `listenbrainz/labs_api/labs/main.py`)