# metabrainz/musicbrainz-server architecture

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

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

## Overview

MusicBrainz Server is the web frontend for a community-maintained music metadata database. A browser request enters the clustered Node server, is dispatched to a page or domain route, reads or updates PostgreSQL-backed metadata, and returns a shared React-rendered layout. Major domain stages include catalog browsing, identifiers and relationships, community editing, account management, administration, reporting, and statistics. The graph uses sampled entry, layout, home, statistics, ISRC, and table code; several route-to-database links reflect the README’s documented frontend/database boundary rather than inspected handler implementations.

Main entry points: [`root/server.mjs`](https://github.com/metabrainz/musicbrainz-server/blob/master/root/server.mjs) (Node Server), [`root/layout/index.js`](https://github.com/metabrainz/musicbrainz-server/blob/master/root/layout/index.js) (Shared Layout), [`root/entity`](https://github.com/metabrainz/musicbrainz-server/tree/master/root/entity) (Entity Pages), [`root/statistics/Index.js`](https://github.com/metabrainz/musicbrainz-server/blob/master/root/statistics/Index.js) (Database Statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime Entry"]
  node_server["Node Server<br/>[server.mjs]"]
end

subgraph group_presentation["Web Presentation"]
  node_layout["Shared Layout<br/>[index.js]"]
  node_ui_components["UI Components"]
  node_home["Home Page<br/>[index.js]"]
end

subgraph group_catalog["Music Catalog"]
  node_entity_pages["Entity Pages"]
  node_artist_pages["Artist Catalog"]
  node_release_pages["Release Catalog"]
  node_recording_pages["Recording Catalog"]
  node_identifier_pages["Identifier Lookup<br/>[Index.js]"]
  node_relationships["Entity Relationships"]
end

subgraph group_contribution["Community Contribution"]
  node_edit_workflow["Edit Workflow"]
  node_annotations["Annotations"]
  node_account["User Accounts"]
  node_oauth["OAuth Access"]
end

subgraph group_operations["Operations And Insights"]
  node_admin["Administration"]
  node_reports["Quality Reports"]
  node_statistics["Database Statistics<br/>[Index.js]"]
  node_collections["User Collections"]
  node_cd_lookup["CD Identification"]
  node_cdtoc["Disc ID Matching"]
end

node_browser(("Browser User"))
node_postgres[("MusicBrainz Database")]

node_browser -->|"sends requests"| node_server
node_server -->|"dispatches"| node_home
node_server -->|"dispatches"| node_entity_pages
node_server -->|"dispatches"| node_edit_workflow
node_server -->|"dispatches"| node_account
node_server -->|"dispatches"| node_statistics
node_server -->|"dispatches"| node_admin
node_home -->|"renders"| node_layout
node_entity_pages -->|"renders"| node_layout
node_artist_pages -->|"renders"| node_layout
node_release_pages -->|"renders"| node_layout
node_recording_pages -->|"renders"| node_layout
node_identifier_pages -->|"renders"| node_layout
node_statistics -->|"renders"| node_layout
node_layout -->|"renders"| node_ui_components
node_entity_pages -->|"reads metadata"| node_postgres
node_artist_pages -->|"reads metadata"| node_postgres
node_release_pages -->|"reads metadata"| node_postgres
node_recording_pages -->|"reads metadata"| node_postgres
node_identifier_pages -->|"reads identifiers"| node_postgres
node_relationships -->|"reads and writes"| node_postgres
node_edit_workflow -->|"writes edits"| node_postgres
node_annotations -->|"writes annotations"| node_postgres
node_account -->|"reads and writes"| node_postgres
node_oauth -.->|"authorizes access"| node_account
node_admin -->|"writes administration"| node_postgres
node_reports -->|"reads metadata"| node_postgres
node_statistics -->|"reads counts"| node_postgres
node_collections -->|"reads and writes"| node_postgres
node_cd_lookup -->|"reads releases"| node_postgres
node_cdtoc -->|"matches disc IDs"| node_postgres

click node_server "https://github.com/metabrainz/musicbrainz-server/blob/master/root/server.mjs"
click node_layout "https://github.com/metabrainz/musicbrainz-server/blob/master/root/layout/index.js"
click node_ui_components "https://github.com/metabrainz/musicbrainz-server/tree/master/root/components"
click node_home "https://github.com/metabrainz/musicbrainz-server/blob/master/root/main/index.js"
click node_entity_pages "https://github.com/metabrainz/musicbrainz-server/tree/master/root/entity"
click node_artist_pages "https://github.com/metabrainz/musicbrainz-server/tree/master/root/artist"
click node_release_pages "https://github.com/metabrainz/musicbrainz-server/tree/master/root/release"
click node_recording_pages "https://github.com/metabrainz/musicbrainz-server/tree/master/root/recording"
click node_identifier_pages "https://github.com/metabrainz/musicbrainz-server/blob/master/root/isrc/Index.js"
click node_relationships "https://github.com/metabrainz/musicbrainz-server/tree/master/root/relationship"
click node_edit_workflow "https://github.com/metabrainz/musicbrainz-server/tree/master/root/edit"
click node_annotations "https://github.com/metabrainz/musicbrainz-server/tree/master/root/annotation"
click node_account "https://github.com/metabrainz/musicbrainz-server/tree/master/root/account"
click node_oauth "https://github.com/metabrainz/musicbrainz-server/tree/master/root/oauth2"
click node_admin "https://github.com/metabrainz/musicbrainz-server/tree/master/root/admin"
click node_reports "https://github.com/metabrainz/musicbrainz-server/tree/master/root/report"
click node_statistics "https://github.com/metabrainz/musicbrainz-server/blob/master/root/statistics/Index.js"
click node_collections "https://github.com/metabrainz/musicbrainz-server/tree/master/root/collection"
click node_cd_lookup "https://github.com/metabrainz/musicbrainz-server/tree/master/root/cdstub"
click node_cdtoc "https://github.com/metabrainz/musicbrainz-server/tree/master/root/cdtoc"

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_browser toneBlue
class node_layout,node_ui_components,node_home,node_postgres toneAmber
class node_entity_pages,node_artist_pages,node_release_pages,node_recording_pages,node_identifier_pages,node_relationships toneMint
class node_edit_workflow,node_annotations,node_account,node_oauth toneRose
class node_admin,node_reports,node_statistics,node_collections,node_cd_lookup,node_cdtoc toneIndigo
```

## Components

### Runtime Entry

- [Node Server](https://github.com/metabrainz/musicbrainz-server/blob/master/root/server.mjs): `root/server.mjs`

### Web Presentation

- [Shared Layout](https://github.com/metabrainz/musicbrainz-server/blob/master/root/layout/index.js): `root/layout/index.js`
- [UI Components](https://github.com/metabrainz/musicbrainz-server/tree/master/root/components): `root/components`
- [Home Page](https://github.com/metabrainz/musicbrainz-server/blob/master/root/main/index.js): `root/main/index.js`

### Music Catalog

- [Entity Pages](https://github.com/metabrainz/musicbrainz-server/tree/master/root/entity): `root/entity`
- [Artist Catalog](https://github.com/metabrainz/musicbrainz-server/tree/master/root/artist): `root/artist`
- [Release Catalog](https://github.com/metabrainz/musicbrainz-server/tree/master/root/release): `root/release`
- [Recording Catalog](https://github.com/metabrainz/musicbrainz-server/tree/master/root/recording): `root/recording`
- [Identifier Lookup](https://github.com/metabrainz/musicbrainz-server/blob/master/root/isrc/Index.js): `root/isrc/Index.js`
- [Entity Relationships](https://github.com/metabrainz/musicbrainz-server/tree/master/root/relationship): `root/relationship`

### Community Contribution

- [Edit Workflow](https://github.com/metabrainz/musicbrainz-server/tree/master/root/edit): `root/edit`
- [Annotations](https://github.com/metabrainz/musicbrainz-server/tree/master/root/annotation): `root/annotation`
- [User Accounts](https://github.com/metabrainz/musicbrainz-server/tree/master/root/account): `root/account`
- [OAuth Access](https://github.com/metabrainz/musicbrainz-server/tree/master/root/oauth2): `root/oauth2`

### Operations And Insights

- [Administration](https://github.com/metabrainz/musicbrainz-server/tree/master/root/admin): `root/admin`
- [Quality Reports](https://github.com/metabrainz/musicbrainz-server/tree/master/root/report): `root/report`
- [Database Statistics](https://github.com/metabrainz/musicbrainz-server/blob/master/root/statistics/Index.js): `root/statistics/Index.js`
- [User Collections](https://github.com/metabrainz/musicbrainz-server/tree/master/root/collection): `root/collection`
- [CD Identification](https://github.com/metabrainz/musicbrainz-server/tree/master/root/cdstub): `root/cdstub`
- [Disc ID Matching](https://github.com/metabrainz/musicbrainz-server/tree/master/root/cdtoc): `root/cdtoc`

### Other components

- **Browser User**
- **MusicBrainz Database**

## Connections

- Browser User → Node Server: sends requests
- Node Server → Home Page: dispatches
- Node Server → Entity Pages: dispatches
- Node Server → Edit Workflow: dispatches
- Node Server → User Accounts: dispatches
- Node Server → Database Statistics: dispatches
- Node Server → Administration: dispatches
- Home Page → Shared Layout: renders
- Entity Pages → Shared Layout: renders
- Artist Catalog → Shared Layout: renders
- Release Catalog → Shared Layout: renders
- Recording Catalog → Shared Layout: renders
- Identifier Lookup → Shared Layout: renders
- Database Statistics → Shared Layout: renders
- Shared Layout → UI Components: renders
- Entity Pages → MusicBrainz Database: reads metadata
- Artist Catalog → MusicBrainz Database: reads metadata
- Release Catalog → MusicBrainz Database: reads metadata
- Recording Catalog → MusicBrainz Database: reads metadata
- Identifier Lookup → MusicBrainz Database: reads identifiers
- Entity Relationships → MusicBrainz Database: reads and writes
- Edit Workflow → MusicBrainz Database: writes edits
- Annotations → MusicBrainz Database: writes annotations
- User Accounts → MusicBrainz Database: reads and writes
- OAuth Access → User Accounts: authorizes access
- Administration → MusicBrainz Database: writes administration
- Quality Reports → MusicBrainz Database: reads metadata
- Database Statistics → MusicBrainz Database: reads counts
- User Collections → MusicBrainz Database: reads and writes
- CD Identification → MusicBrainz Database: reads releases
- Disc ID Matching → MusicBrainz Database: matches disc IDs
