# x8rr/music architecture

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

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

## Overview

x8rr/music is a Fastify music backend. Clients use its API to search and browse Tidal catalog data, resolve YouTube Music tracks, and request seekable audio; artwork is served through a cached proxy. Internally, YouTube Music audio is cached on disk with optional R2 persistence, while cache sweeping and source health support operation. The graph preserves README capabilities whose route implementations were not sampled; edges for those are limited to documented relationships or indexed imports. Unsampled route details are not inferred.

Main entry points: [`routes/music.ts`](https://github.com/x8rr/music/blob/main/routes/music.ts) (Music API), [`lib/ytm.ts`](https://github.com/x8rr/music/blob/main/lib/ytm.ts) (Audio acquisition), [`lib/artCache.ts`](https://github.com/x8rr/music/blob/main/lib/artCache.ts) (Artwork proxy), [`index.ts`](https://github.com/x8rr/music/blob/main/index.ts) (Fastify server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_server["Fastify server<br/>[index.ts]"]
  node_web["Web interface<br/>[index.html]"]
  node_routes["Music API<br/>[music.ts]"]
end

subgraph group_catalog["Catalog and sources"]
  node_source_config["Source configuration<br/>[music-sources.json]"]
  node_tidal["Tidal catalog<br/>[tidal.ts]"]
  node_ytm_search["YouTube Music search<br/>[ytm.ts]"]
  node_music_sources(("Music providers"))
end

subgraph group_media["Media delivery"]
  node_audio_cache["Audio acquisition<br/>[ytm.ts]"]
  node_range_proxy["Range streaming<br/>[rangeProxy.ts]"]
  node_art_proxy["Artwork proxy<br/>[artCache.ts]"]
end

subgraph group_runtime["Cache and resilience"]
  node_art_files[("Artwork disk cache<br/>[artCache.ts]")]
  node_audio_files[("Audio disk cache<br/>[ytm.ts]")]
  node_r2[("R2 object store<br/>[r2.ts]")]
  node_sweeper["Cache sweeper<br/>[cacheSweep.ts]"]
  node_breaker["Source breaker<br/>[sourceBreaker.ts]"]
  node_lru["Memory cache<br/>[lruCache.ts]"]
  node_gate["Download gate<br/>[concurrencyGate.ts]"]
  node_bounded_body["Bounded body reader<br/>[readBodyAtMost.ts]"]
end

node_listener(("Music client"))

node_listener -->|"requests"| node_server
node_server -->|"registers"| node_routes
node_server -->|"serves"| node_web
node_server -->|"starts"| node_sweeper
node_routes -->|"loads"| node_source_config
node_routes -->|"searches"| node_tidal
node_routes -->|"searches"| node_ytm_search
node_routes -->|"fetches audio"| node_audio_cache
node_routes -->|"streams ranges"| node_range_proxy
node_routes -->|"gets artwork"| node_art_proxy
node_tidal -->|"queries"| node_music_sources
node_ytm_search -->|"searches"| node_music_sources
node_audio_cache -.->|"downloads audio"| node_music_sources
node_audio_cache -->|"reads and writes"| node_audio_files
node_audio_cache -->|"restores and stores"| node_r2
node_audio_cache -->|"limits downloads"| node_gate
node_audio_cache -->|"caches lookups"| node_lru
node_art_proxy -->|"reads and writes"| node_art_files
node_art_proxy -->|"restores and stores"| node_r2
node_art_proxy -->|"bounds reads"| node_bounded_body
node_art_proxy -->|"touches cache"| node_sweeper
node_sweeper -.->|"evicts files"| node_art_files
node_sweeper -.->|"evicts files"| node_audio_files
node_routes -.->|"reports source health"| node_breaker

click node_server "https://github.com/x8rr/music/blob/main/index.ts"
click node_web "https://github.com/x8rr/music/blob/main/public/index.html"
click node_routes "https://github.com/x8rr/music/blob/main/routes/music.ts"
click node_source_config "https://github.com/x8rr/music/blob/main/config/music-sources.json"
click node_tidal "https://github.com/x8rr/music/blob/main/lib/tidal.ts"
click node_ytm_search "https://github.com/x8rr/music/blob/main/lib/ytm.ts"
click node_audio_cache "https://github.com/x8rr/music/blob/main/lib/ytm.ts"
click node_range_proxy "https://github.com/x8rr/music/blob/main/lib/rangeProxy.ts"
click node_art_proxy "https://github.com/x8rr/music/blob/main/lib/artCache.ts"
click node_art_files "https://github.com/x8rr/music/blob/main/lib/artCache.ts"
click node_audio_files "https://github.com/x8rr/music/blob/main/lib/ytm.ts"
click node_r2 "https://github.com/x8rr/music/blob/main/lib/r2.ts"
click node_sweeper "https://github.com/x8rr/music/blob/main/lib/cacheSweep.ts"
click node_breaker "https://github.com/x8rr/music/blob/main/lib/sourceBreaker.ts"
click node_lru "https://github.com/x8rr/music/blob/main/lib/lruCache.ts"
click node_gate "https://github.com/x8rr/music/blob/main/lib/concurrencyGate.ts"
click node_bounded_body "https://github.com/x8rr/music/blob/main/lib/readBodyAtMost.ts"

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_web,node_routes,node_listener toneBlue
class node_source_config,node_tidal,node_ytm_search,node_music_sources toneAmber
class node_audio_cache,node_range_proxy,node_art_proxy toneMint
class node_art_files,node_audio_files,node_r2,node_sweeper,node_breaker,node_lru,node_gate,node_bounded_body toneRose
```

## Components

### API and UI

- [Fastify server](https://github.com/x8rr/music/blob/main/index.ts): `index.ts`
- [Web interface](https://github.com/x8rr/music/blob/main/public/index.html): `public/index.html`
- [Music API](https://github.com/x8rr/music/blob/main/routes/music.ts): `routes/music.ts`

### Catalog and sources

- [Source configuration](https://github.com/x8rr/music/blob/main/config/music-sources.json): `config/music-sources.json`
- [Tidal catalog](https://github.com/x8rr/music/blob/main/lib/tidal.ts): `lib/tidal.ts`
- [YouTube Music search](https://github.com/x8rr/music/blob/main/lib/ytm.ts): `lib/ytm.ts`
- **Music providers**

### Media delivery

- [Audio acquisition](https://github.com/x8rr/music/blob/main/lib/ytm.ts): `lib/ytm.ts`
- [Range streaming](https://github.com/x8rr/music/blob/main/lib/rangeProxy.ts): `lib/rangeProxy.ts`
- [Artwork proxy](https://github.com/x8rr/music/blob/main/lib/artCache.ts): `lib/artCache.ts`

### Cache and resilience

- [Artwork disk cache](https://github.com/x8rr/music/blob/main/lib/artCache.ts): `lib/artCache.ts`
- [Audio disk cache](https://github.com/x8rr/music/blob/main/lib/ytm.ts): `lib/ytm.ts`
- [R2 object store](https://github.com/x8rr/music/blob/main/lib/r2.ts): `lib/r2.ts`
- [Cache sweeper](https://github.com/x8rr/music/blob/main/lib/cacheSweep.ts): `lib/cacheSweep.ts`
- [Source breaker](https://github.com/x8rr/music/blob/main/lib/sourceBreaker.ts): `lib/sourceBreaker.ts`
- [Memory cache](https://github.com/x8rr/music/blob/main/lib/lruCache.ts): `lib/lruCache.ts`
- [Download gate](https://github.com/x8rr/music/blob/main/lib/concurrencyGate.ts): `lib/concurrencyGate.ts`
- [Bounded body reader](https://github.com/x8rr/music/blob/main/lib/readBodyAtMost.ts): `lib/readBodyAtMost.ts`

### Other components

- **Music client**

## Connections

- Music client → Fastify server: requests (evidence: `README.md`)
- Fastify server → Music API: registers (evidence: `index.ts`)
- Fastify server → Web interface: serves (evidence: `index.ts`)
- Fastify server → Cache sweeper: starts (evidence: `index.ts`)
- Music API → Source configuration: loads (evidence: `routes/music.ts`)
- Music API → Tidal catalog: searches (evidence: `routes/music.ts`)
- Music API → YouTube Music search: searches (evidence: `routes/music.ts`)
- Music API → Audio acquisition: fetches audio (evidence: `routes/music.ts`)
- Music API → Range streaming: streams ranges (evidence: `README.md`)
- Music API → Artwork proxy: gets artwork (evidence: `routes/music.ts`)
- Tidal catalog → Music providers: queries (evidence: `lib/tidal.ts`)
- YouTube Music search → Music providers: searches (evidence: `lib/ytm.ts`)
- Audio acquisition → Music providers: downloads audio
- Audio acquisition → Audio disk cache: reads and writes (evidence: `lib/ytm.ts`)
- Audio acquisition → R2 object store: restores and stores (evidence: `lib/ytm.ts`)
- Audio acquisition → Download gate: limits downloads (evidence: `lib/concurrencyGate.ts`)
- Audio acquisition → Memory cache: caches lookups (evidence: `lib/ytm.ts`)
- Artwork proxy → Artwork disk cache: reads and writes (evidence: `lib/artCache.ts`)
- Artwork proxy → R2 object store: restores and stores (evidence: `lib/artCache.ts`)
- Artwork proxy → Bounded body reader: bounds reads (evidence: `lib/artCache.ts`)
- Artwork proxy → Cache sweeper: touches cache (evidence: `lib/artCache.ts`)
- Cache sweeper → Artwork disk cache: evicts files (evidence: `lib/artCache.ts`)
- Cache sweeper → Audio disk cache: evicts files
- Music API → Source breaker: reports source health (evidence: `routes/music.ts`)
