FSD Frontend System Design

Part VI — The Blueprint · Lesson 11.6

HLD – Music Streaming (Spotify)

In one lineThe player must survive navigation, so it lives above the router — everything else follows from that.

Where you've seen itClicking through albums, artists, and search while playback never pauses for even a frame.

  • Time18 min
  • DiagramPlayer above the route tree + queue state machine
  • Chapter11 · High Level Design

Diagram

diagram
1–2 · SCOPE AND SCALE

  in scope   browse · search · album/playlist · player · queue · offline
  out        podcasts · social · ads · artist tools
  scale      600M users · tracks ~3MB at 160kbps
             sessions measured in hours, not minutes
diagram
3 · THE ARCHITECTURAL DECISION — player OUTSIDE the router

  ┌──────────────────────── App shell ─────────────────────────┐
  │  ┌───────────────────────────────────────────────────────┐ │
  │  │  <Router>   ← everything here unmounts on navigate    │ │
  │  │    /browse   /album/:id   /search   /playlist/:id     │ │
  │  └───────────────────────────────────────────────────────┘ │
  │  ┌───────────────────────────────────────────────────────┐ │
  │  │  <Player>   ← single <audio> element, NEVER unmounts  │ │
  │  │  play/pause · seek · queue · volume                   │ │
  │  └───────────────────────────────────────────────────────┘ │
  └────────────────────────────────────────────────────────────┘

  Put <audio> inside a route and every navigation restarts the song.
  This single decision is most of the answer.
diagram
6a · DEEP DIVE — QUEUE STATE MACHINE

  [idle] ──play(track)──► [loading] ──canplay──► [playing]
                              │                    │  │
                              │              pause │  │ ended
                              ▼                    ▼  ▼
                          [error]              [paused] [next?]
                         retry / skip                     │
                                              ┌───────────┴────────┐
                                          queue empty          more
                                              │                  │
                                           [idle]           [loading]

  queue = { context: 'album:42', items: [...],
            index: 3, shuffle: false, repeat: 'off'|'one'|'all' }
  Shuffle stores a shuffled ORDER, not a shuffled array — so
  turning it off restores the original sequence.
diagram
6b · DEEP DIVE — GAPLESS PLAYBACK AND PREFETCH

  now playing  ████████████████████░░░░  80%
                                     │
                                     └─► start fetching next track
                                         (two <audio> elements,
                                          swap on ended → no gap)

  offline (9.1)  downloaded tracks → IndexedDB (6.5)
                 served by the service worker on request
                 licence/expiry checked before playback

How it works

  1. Single audio element above the router, driven by a global player store (10.5) — routes only dispatch intents.
  2. Queue as explicit state: context, items, index, shuffle order, repeat mode.
  3. Prefetch the next track at ~80% and use a second audio element for gapless transitions.
  4. Media Session API wires lock-screen controls, hardware keys, and metadata.
  5. Offline stores downloaded audio in IndexedDB and serves it through the service worker.

Trade-offs

ChoiceCost
Player outside routerApp shell can't be fully route-code-split
Two audio elementsMore memory; gapless transitions
Prefetch next trackWasted data if the user skips
Offline downloadsStorage quota, licensing, eviction handling

Interview angle

"Music stops when the user navigates. Why, and how do you fix it?"

  • The <audio> element is inside a route, so navigation unmounts and recreates it.
  • Hoist a single player instance above the router and drive it from a global store; routes dispatch play/pause intents only.
  • Then add Media Session so hardware and lock-screen controls work, which is expected behaviour for anything audio.

Recap

  • The player lives above the router — that's the design.
  • Queue is explicit state: context, index, shuffle order, repeat mode.
  • Prefetch at ~80% and swap audio elements for truly gapless playback.