BBC 6 Music → Spotify Sync: Learning Guide

Learning Guide: BBC 6 Music → Spotify Sync

Every Monday, BBC Radio 6 Music publishes the list of songs its DJs will be playing that week. Every Tuesday at midnight, a small Node.js process on a VPS wakes up, reads that page, finds each song on Spotify, and drops it into a playlist named for the month, such as "BBC 6 Music Oct 2026". Nobody touches it. When something goes wrong, it sends an email.

That's the whole product, and it fits in one sentence. Making it work properly took most of 2026. This pack explains how it works, why it was built this way, what went wrong along the way, and what's still wrong today.

Who this is for

You, the person who built it with an AI pair and now wants to own it. Each guide explains a part well enough that you could take questions on it from a senior engineer or a hiring manager. Every guide ends with "Questions you might get asked" and the answers you'd give.

The guides

# Guide Read it to understand
1 The big picture The parts, how one weekly run flows, and the overall shape of the design
2 The BBC side Scraping a page that has no API, and how that breaks
3 The Spotify side OAuth, refresh tokens, playlists, rate limits
4 The matcher How "Bleachers – you and forever" becomes one Spotify track, and how it once became Pavarotti
5 Scheduling, state and recovery Cron, timezones, JSON state, duplicates, tombstones, email, logs
6 Tests TDD, the 607 Jest tests, the Bash deploy tests, and what tests can't catch
7 CI/CD GitHub Actions: how a merge becomes a running release
8 The server Plesk, PM2, systemd, SSH keys, the release-folder layout
9 History and lessons How the plan changed from 2022 to now, and what it taught
10 Known flaws Problems found while writing this pack, ready to become issues

If you only have an hour, read 1, 4 and 9. They cover the design, the hardest problem, and the story.

How to use this pack

  • Read with the code open. Every claim links to a file. The code is the truth, and where these guides and the code disagree, the code wins.
  • Run things. npm test takes about 45 seconds. npx ts-node scripts/test-matcher.ts "Bleachers" "you and forever" shows the matcher's reasoning against real Spotify data (it needs your config/settings.json).
  • Older docs. The technical spec, ADRs and implementation plan were written before most of the code. They show what was intended. This pack shows what actually happened, including where those documents turned out to be wrong.

Written 27 October 2026, against main plus the unmerged feat/21-continuous-deployment branch. Deploy files marked † live on that branch until it merges.