Requirements

Functional Requirements:

• Allow user to stream music - pause, play, skip
• Allow user to manage playlists - create, edit, delete
• Allow users to search for songs, artists, and albums
• Allow users to like songs
• Personalized recommendations (home feed)
• Allow offline music streaming

Non-Functional Requirements:

• Highly scalable: support ~50M DAU and ~1B daily streams
• Highly available: 99.9% uptime for playback
• Strong consistency for billing/subscription
• Eventual consistency for playlists, home feed, and likes
• High streaming throughput: <300ms latency for audio start
• <200ms latency for search

Capacity Estimation

• 500M users
• 50M DAU
• 100M songs library
• Avg ~5MB song size (compressed)

Storage: 100M x 5MB = 500TB raw data

Streaming bandwidth:

• 50M dau
• 20 songs/day/user: ~3min per song
• ~1B streams/day
• Bandwidht per stream : 160kbps
• Total bandwidth: ~180-250 gbps sustained global traffic

API Design

Playlists:

POST /playlists

GET /playlists/{id}

PUT /playlists -> update/soft-delete playlist

req - {

status : 'InActive'

}

POST /playlists/{id}/song -> Add song

PUT /playlists/{id}/song -> soft-delete song from playlist

Playback:

GET /songs/{id}

• returns song metadata which includes a manifest file url
• Manifest file contains: singed CDN url, bitrate options etc

Search:

GET /search?q=XYZ?cursor=id

-> returns: songs, artists, albums matching the query

GET /home-feed

-> returns users's personalized home feed (songs)

Like songs:

POST /songs/{id}/like

High-Level Design

API Gateway

Acts as the entry point for all client requests.

Responsibilities:

• Authentication (if required)
• Rate limiting - Applied using token bucket per IP to prevent fraudulent or bot views
• Request routing

Load Balancer

Distributes traffic across multiple instances of all services to improve scalability and availability.

User Service/Playlist Service -> CRUD operations for both user and playlists

Streaming service:

Responsibilities

• Recieves song streaming request
• Fetches that song's metadata via redis
• Uses Cassandra as fallback if cache miss from redis
• Returns back metadata thja contains the manifest file url for streaming options

Search Service

Responsibilities

• Recieves a search query
• Normalizes the query in a standard format
• Fetches top K song ids from in elastic search index
• Enrich the song metadata from redis/cassandra
• returns ~20 records

ElasticSearcgh

• Inverted index
• Stores
  • Keyword ->list of songs, artists, albums

Event collection service

Responsibilties:

• Each user event such as pause, play, skip, like all comes to this service
• The service is validates and emits the event to kafka

Kafka:

• Event backbone
• Uses userId as partition key for all events
• Gurantees at least once delivery

Flink:

• Consumes events from kafka
• Updates event-related data in-memory
  • eg: userId123: {rockAffinity: 0.7, likeRate:0.6} etc
• Flushes the data aggreated to feature store

Feature store / ML Model:

• Part of personalized recommednation generation
• Feature store acts as a centralized data, ML model consumes those data periodically and trains the recommendation model.

Feed/Recommendation Service:

• Responsioble for recommednation generation:
  • uses ML model to check user preferences computed via user events
  • Using user prefeneces generates top k ranked recommended song
  • Stores in redis. Cassandra as fallback
• Also receives get home feed request
• Fetches home feed of user from redis (cassandra as fallback) and returns it

Redis:

• Caching layer
• Stores:
  • Hot/Trending Song metadata -> LRU -> TTL ~ 24 hrs
    • eg: song123:{title, cdn url, genre, duration}
  • User home feed - already ranked
    • eg: UserId :{song123,song456,song789}

Database Design

We use a hybrid SQL (PostgreSQL) + NoSQL (Cassandra) architecture.

• SQL is used for strongly consistent relational data like Users, PlayLists, PlayListSongs
• NoSQL (Cassandra) is used for high-scale data like Songs, Artists, Albums, due to its horizontal scalability and high write throughput.

Users

id

name

email

country (partition key)

Playlist

id

name

user_id (partition key)

status

PlaylistSongs

id

playlistId (partition key)

songId

position

Status

Songs

id

title

artist_id

album_id

duration

genre

-> artist id + album id as partition key

Artists

id

name

status

Albums

id

artist_id

songs[]

released_date

Detailed Component Design

We will now deep dive in the following topics:

Deep Dive #1: Recommendation System

• The recommendation system is built as a multi-stage pipeline: event ingestion, feature computation, offline training, candidate generation, ranking, and serving.

Event Ingestion & Feature Store

• User actions (play, skip, like) are sent to Kafka.

• Kafka is partitioned by userId to preserve ordering of user behavior, which is critical for correct preference modeling.
• Flink computes real-time features like:
  • Genre affinity
  • Skip rate
  • Like rate
• These are stored in a Feature Store for training and inference.

Offline Training

Models are trained offline for stability, reproducibility, and cost efficiency. Versioned models are deployed via a Model Registry.

Candidate Generation

Instead of ranking 100M songs, we first generate ~500 candidates using:

• User’s preferred genres
• Collaborative filtering
• Trending songs
• New releases
• Similar artists

This reduces ranking cost significantly.

Ranking & Feed Serving

Each candidate is scored using an ML model based on:

• User preferences
• Song features (popularity, freshness)
• Context (time, device)

Top 50–100 songs are selected and precomputed into Redis:

Redis enables sub-50ms feed retrieval, with Cassandra as fallback.

Freshness

Flink continuously updates user features. If a major behavior shift is detected (e.g., Rock → Jazz), we trigger partial feed regeneration to keep recommendations fresh.

Deep Dive #2: Search System

Search is powered by Elasticsearch with an event-driven indexing pipeline:

Search queries go through:

Elasticsearch handles relevance ranking, while Redis/Cassandra is used for metadata enrichment.

System is horizontally scalable with cached hot queries.

Deep Dive #3: Multi-Region & Failure Handling

The system is deployed across multiple regions for low latency and high availability.

Streaming

Audio is served via CDN with fallback to object storage.

Data Layer

• Cassandra: multi-region replication (eventual consistency)
• Redis: regional caches for feeds
• Stateless services: active-active deployment

Failure Handling

• Kafka: replayable log, at-least-once delivery
• Flink: checkpoint-based recovery
• Redis: rebuilt from Cassandra
• Elasticsearch: rebuildable from Kafka/source data
• Models: fallback to last stable version

Tradeoffs

• Prioritize availability over strict consistency for recommendations/search
• Precomputed feeds for low latency
• Eventual consistency is acceptable for personalization systems