Prelude.

Project summary

Prelude pulls the music metadata layer out of individual apps and turns it into one reusable service. Resleeve and future music projects can ask Prelude for albums, artists and songs instead of each app calling MusicBrainz directly.

Problem being solved

MusicBrainz has strict rate limits and a detailed data model. Multiple apps calling it independently would duplicate cache logic, repeat slow requests and risk throttling the entire stack from one public IP.

Target users

The direct users are my own backend applications. The indirect users are anyone using those apps, because they get faster album lookups and more reliable artwork without seeing the infrastructure doing the work.

Architecture overview

FastAPI exposes retrieval and search endpoints. PostgreSQL stores normalized music items plus raw JSON responses. Redis coordinates in-flight work and negative cache entries. Celery runs the single outbound request worker so all MusicBrainz traffic passes through one polite rate-limited queue.

Important technical decisions

Search stays authoritative and still asks MusicBrainz, while exact ID retrieval is cache-first. This keeps discovery accurate but makes repeated known lookups fast. Cloudflare Access protects the service so only my applications and authenticated operator sessions can use it.

Difficult problems and solutions

The biggest risk was duplicate misses. If many users request the same uncached album, Prelude uses an atomic Redis claim so only one job fetches it and the rest wait for the cached row. Missing IDs get a short negative cache so repeated bad requests fail quickly.

Results and lessons learned

Prelude gives the rest of the stack one dependable music catalogue. The main lesson was that a small internal service still needs product-level thinking: failure modes, timeouts, access control and observability matter even when there is no public UI.

Related writing

Building Prelude: a shared music catalogue for the whole stack.