How metabrainz/listenbrainz-server works
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: userRoutes.tsx User routes · incremental_stats_engine.py Incremental stats · __init__.py ListenBrainz web app · routes.tsx Frontend routes
Components 20
Web experience
- ListenBrainz web app
listenbrainz/webserver/__init__.py - Frontend routes
frontend/js/src/routes/routes.tsx - User routes
frontend/js/src/user/routes/userRoutes.tsx - Listening dashboard
frontend/js/src/user/Dashboard.tsx - Year in Music
frontend/js/src/user/year-in-music/YearInMusic.tsx
Listening data
- Listen API
listenbrainz/webserver/views/api.py - Listen storage
listenbrainz/listenstore/timescale_listenstore.py - Timescale access
listenbrainz/db/timescale.py - Listen importers
listenbrainz/background/listens_importer
Insights and discovery
- Incremental stats
listenbrainz_spark/stats/incremental/incremental_stats_engine.py - Spark listen data
listenbrainz_spark/listens/data.py - Spark query dispatch
listenbrainz_spark/query_map.py - Spark result handlers
listenbrainz/spark/handlers.py - Popularity analytics
listenbrainz_spark/popularity/main.py
Integrations and data
- Music-service links
listenbrainz/domain/external_service.py - OAuth records
listenbrainz/db/external_service_oauth.py - Labs metadata APIs
listenbrainz/labs_api/labs/main.py - Dump management
listenbrainz/dumps/manager.py - Dump listen store
listenbrainz/listenstore/dump_listenstore.py
Other components
- Listener
Connections 15
- Listener → ListenBrainz web app: uses
- ListenBrainz web app → Frontend routes: serves experience
- Frontend routes → User routes: routes users
frontend/js/src/routes/routes.tsx - User routes → Listening dashboard: loads dashboard
frontend/js/src/user/routes/userRoutes.tsx - User routes → Year in Music: loads year views
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
listenbrainz/domain/external_service.py - Incremental stats → Spark listen data: loads listen data
listenbrainz_spark/stats/incremental/incremental_stats_engine.py - Incremental stats → Popularity analytics: computes aggregates
listenbrainz_spark/popularity/main.py - Spark query dispatch → Popularity analytics: dispatches queries
listenbrainz_spark/query_map.py - Spark result handlers → Listening dashboard: stores user stats
- Dump management → Dump listen store: creates listen dumps
listenbrainz/dumps/manager.py - Listener → Labs metadata APIs: queries metadata
listenbrainz/labs_api/labs/main.py