metadata-agregator/docs/research/musicbrainz-server/analysis/OVERVIEW.md

MusicBrainz Server Overview

Project Identity

Name: MusicBrainz Server
Repository: https://github.com/metabrainz/musicbrainz-server
License: GPL-2.0+
Description: Open music encyclopedia that collects music metadata and makes it available to the public. Community-maintained database of music information including artists, releases, recordings, works, labels, and the relationships between them.

Technology Stack

Backend

Primary Language: Perl 5.38+
Web Framework: Catalyst (MVC framework)
Object System: Moose (modern Perl OOP)

Core Perl Dependencies:

• Catalyst::Runtime - Web application framework
• Moose - Modern object system for Perl
• DBD::Pg - PostgreSQL database driver
• Template::Toolkit - Template processing system
• Plack - PSGI toolkit and server adapters
• Redis - Perl Redis client
• JSON::XS - Fast JSON encoding/decoding
• XML::LibXML - XML processing
• DBIx::Connector - Fast, safe DBI connection management
• Readonly - Facility for creating read-only scalars, arrays, hashes
• Digest::SHA - SHA message digest algorithm
• LWP::UserAgent - HTTP client
• DateTime - Date and time object
• List::AllUtils - List manipulation utilities
• Try::Tiny - Minimal try/catch
• Class::Load - Load modules by name
• namespace::autoclean - Keep imports out of namespace

Frontend

Primary Language: JavaScript (ES6+)
UI Framework: React 19.2.4
State Management: Redux
Legacy Framework: Knockout.js (still present in some views)

Core JavaScript Dependencies:

• React 19.2.4 - UI component library
• Redux - State management
• Webpack 5 - Module bundler
• Babel 7 - JavaScript compiler
• knockout - Legacy MVVM framework
• jQuery - DOM manipulation (legacy)
• lodash - Utility library
• immutable - Immutable data structures
• weight-balanced-tree - Efficient tree data structure

Infrastructure

Database: PostgreSQL 16+

• 375 tables
• 500+ foreign key constraints
• Full-text search capabilities
• Custom replication via dbmirror2

Cache: Redis

• 16 separate databases
• Entity caching
• Session storage
• Pub/sub messaging

Search: Apache Solr

• Primary search engine
• PostgreSQL full-text as fallback

Message Queue: RabbitMQ (for background jobs)

System Prerequisites

Required:

• Perl 5.38+ (5.42.0 tested in CI)
• Node.js 20.9+
• PostgreSQL 16+
• Redis 6.0+
• Apache Solr 8.11+

Optional:

• Docker + Docker Compose (for containerized deployment)
• RabbitMQ (for background job processing)

Entry Point

File: app.psgi

Initialization Flow:

1. app.psgi loads the Plack middleware stack
2. Initializes MusicBrainz::Server Catalyst application
3. Loads configuration from DBDefs.pm
4. Establishes database connections via DBIx::Connector
5. Initializes Redis connection pool
6. Forks template renderer process for isolation
7. Loads Catalyst controllers, models, and views
8. Mounts PSGI application

Middleware Stack:

• Plack::Middleware::ReverseProxy - Handle X-Forwarded headers
• Plack::Middleware::Static - Serve static files
• Plack::Middleware::Session - Session management
• Custom middleware for CSRF protection
• Custom middleware for request logging

Codebase Scale

Perl:

• 1,866 Perl files
• 53 controllers (13,000 lines)
• 106 Data modules (26,000 lines)
• 132 entity classes
• 43 form modules
• 4 view modules

JavaScript:

• 1,447 JavaScript files
• React components
• Redux reducers and actions
• Legacy Knockout view models

Database:

• 375 tables
• 332 migration files
• 4,068 lines in CreateTables.sql

Tests:

• Perl unit tests (t/)
• JavaScript tests (Jest)
• pgTAP database tests
• Selenium integration tests (4 partitions)

Build Process

Perl Dependencies

# Install Carton (Perl dependency manager)
cpanm Carton

# Install Perl dependencies from cpanfile.snapshot
carton install

JavaScript Dependencies

# Install Node.js dependencies
yarn install

Asset Compilation

# Compile static resources (CSS, images, fonts)
./script/compile_resources.sh

# Build JavaScript bundles with Webpack
yarn run build

Build Outputs:

• root/static/build/ - Compiled JavaScript bundles
• root/static/styles/ - Compiled CSS
• root/static/images/ - Optimized images

Run Commands

Development

# Using plackup (development server)
plackup -Ilib -r app.psgi

# With auto-reload on file changes
plackup -Ilib -R lib,root -r app.psgi

Production

# Using Starman (production PSGI server)
starman --workers 10 --listen :5000 app.psgi

# Using Server::Starter for zero-downtime restarts
start_server --port 5000 -- starman --workers 10 app.psgi

Docker

# Build Docker images
docker-compose build

# Start all services
docker-compose up -d

# Start specific service
docker-compose up -d website

Available Services:

• website - Main web application
• webservice - API service
• cron - Scheduled tasks
• sitemaps - Sitemap generation
• json-dump - JSON data dumps
• solr-backup - Solr index backup
• tests - Test runner

Directory Structure

musicbrainz-server/
├── admin/              # Database schema and migrations
│   ├── sql/
│   │   ├── CreateTables.sql
│   │   └── updates/    # 332 migration files
├── lib/                # Perl application code
│   └── MusicBrainz/
│       └── Server/
│           ├── Controller/  # 53 controllers
│           ├── Data/        # 106 data access modules
│           ├── Entity/      # 132 entity classes
│           ├── Form/        # 43 form handlers
│           ├── View/        # 4 view modules
│           ├── WebService/  # API implementation
│           └── Edit/        # Edit system
├── root/               # Frontend assets
│   ├── static/         # Static files
│   │   ├── scripts/    # JavaScript source
│   │   ├── styles/     # CSS/LESS
│   │   └── images/
│   └── layout.tt       # Main template
├── t/                  # Perl tests
├── docker/             # Docker configuration
├── script/             # Utility scripts
├── app.psgi            # PSGI entry point
├── cpanfile            # Perl dependencies
├── package.json        # Node.js dependencies
└── webpack.config.js   # Webpack configuration

Configuration

Primary Config: lib/DBDefs.pm

Two-Tier System:

1. lib/DBDefs/Default.pm - Default values
2. lib/DBDefs.pm - Instance-specific overrides (not in git)

Key Configuration Areas:

• Database connection strings
• Redis connection parameters
• Solr endpoints
• External service credentials (Cover Art Archive, Wikipedia, etc.)
• Session settings
• Email configuration
• OAuth2 settings
• Feature flags

Status

Active Development: Continuous development since 2001 (15+ years)
Production Status: Stable, serving millions of requests daily
Community: Large open-source community with hundreds of contributors
Data Quality: Community-driven editing with voting system ensures high quality
API Usage: Powers metadata for major music services and applications worldwide