🎵 Playlist & Recommendation Service API

A production-grade mini Spotify backend built with FastAPI — implementing classic System Design patterns: Strategy, Observer, Repository, and Cache-Aside, over a clean layered architecture.

---

📌 Overview

This project is a System Design case study built as a real, runnable FastAPI application. It demonstrates how to architect a scalable music streaming backend from scratch — covering playlist management, three-strategy recommendation engine, Redis caching, token-bucket rate limiting, and observer-based notifications.

What this project teaches:

• How to apply Gang of Four design patterns in a real Python service
• How Cache-Aside pattern reduces database load by ~10×
• How the Strategy pattern enables pluggable, swappable algorithms
• How the Observer pattern decouples event producers from consumers
• How the Repository pattern cleanly separates business logic from data access

---

✨ Features

Feature	Description	Pattern Used
🎵 Playlist CRUD	Create, read, update, delete playlists; add/remove songs	Repository Pattern
🤖 Recommendation Engine	3 strategies: Popularity, Content-Based, Collaborative Filtering	Strategy Pattern
⚡ Redis Caching	Cache-aside with 10-minute TTL; 10× faster reads	Cache-Aside Pattern
🚦 Rate Limiting	Token Bucket — 100 req/min per user via X-User-Id header	Middleware
🔔 Notifications	Email + Push notifications on playlist events (simulated)	Observer Pattern
🌐 Frontend UI	Served static SPA at / for interactive API exploration	FastAPI Static Files
🧪 Test Suite	Full pytest coverage for playlists, cache, rate limiter, recommendations	pytest + httpx

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                        Client                           │
│               (Browser / API / curl)                    │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP
┌──────────────────────▼──────────────────────────────────┐
│              Rate Limiter Middleware                     │
│         Token Bucket: 100 req/min per user              │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                  FastAPI Routes                         │
│        /playlists  /recommendations  /songs             │
└──────────┬──────────────────────────┬───────────────────┘
           │                          │
┌──────────▼─────────┐   ┌───────────▼────────────────────┐
│   Playlist Service │   │     Recommendation Engine      │
│  + EventManager    │   │  Strategy: popularity /        │
│    (Observer)      │   │  content_based / collaborative │
└──────────┬─────────┘   └───────────┬────────────────────┘
           │                         │
┌──────────▼─────────────────────────▼───────────────────┐
│                   Cache Layer (Redis)                   │
│         CacheManager — Cache-Aside Pattern              │
│         TTL: 600s │ fakeredis (zero-setup)              │
└──────────────────────┬──────────────────────────────────┘
                       │ cache miss
┌──────────────────────▼──────────────────────────────────┐
│               Repository Layer                          │
│       PlaylistRepository │ SongRepository               │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│               Database (SQLite + SQLAlchemy)            │
└─────────────────────────────────────────────────────────┘

---

🧩 Design Patterns in Detail

🎯 Strategy Pattern — Recommendation Engine

The RecommendationEngine acts as a context that holds a pluggable RecommendationStrategy. The active algorithm can be switched at runtime via the ?strategy= query parameter — no code changes needed.

# Three concrete strategies, all implementing the same interface
STRATEGY_MAP = {
    "popularity":    PopularityBasedStrategy,    # top trending songs
    "content_based": ContentBasedStrategy,       # genre/artist match
    "collaborative": CollaborativeFilteringStrategy,  # Jaccard similarity
}

engine = RecommendationEngine(strategy_name="collaborative")
songs  = engine.get_recommendations(db, user_id="u1", n=10)

👁️ Observer Pattern — Notifications

The EventManager (Subject) maintains a registry of Observer implementations. When a playlist event fires, all registered observers are notified — fully decoupled from the service layer.

EventManager ──subscribe──► EmailNotifier  (logs simulated email)
             ──subscribe──► PushNotifier   (logs simulated push)

# Events: PLAYLIST_CREATED, SONG_ADDED, PLAYLIST_UPDATED
event_manager.notify(EventType.SONG_ADDED, {"playlist_id": "...", "song_id": "..."})

🗄️ Repository Pattern — Data Access

All database queries are behind PlaylistRepository and SongRepository. The service layer never writes raw SQL — it calls typed methods like get_by_user_id() or get_top_by_popularity().

⚡ Cache-Aside Pattern — Redis

READ  → check cache → HIT: return cached data
                    → MISS: query DB → populate cache → return data
WRITE → update DB → invalidate cache key

Metric	Without Cache	With Cache
Response Time	~50ms	~5ms
DB Load	High	Low
Scalability	Medium	High

🚦 Token Bucket Rate Limiter

Each user (X-User-Id header or IP) gets a bucket of 100 tokens that refills at 100 tokens/minute. Exceeding the limit returns HTTP 429 with a Retry-After header.

---

📁 Project Structure

Playlist & Recommendation API/
│
├── app/
│   ├── main.py                        # FastAPI app, startup wiring
│   ├── config.py                      # All config constants (TTL, rate limits, DB URL)
│   ├── database.py                    # SQLAlchemy engine, session factory, init_db()
│   │
│   ├── models/
│   │   ├── playlist.py                # ORM models: PlaylistORM, SongORM, association table
│   │   └── response.py                # Pydantic APIResponse wrapper
│   │
│   ├── repositories/
│   │   ├── base.py                    # Abstract BaseRepository
│   │   ├── playlist_repo.py           # PlaylistRepository (CRUD + user queries)
│   │   └── song_repo.py               # SongRepository (catalog, genre filter, seed data)
│   │
│   ├── services/
│   │   ├── playlist_service.py        # Business logic for playlist operations
│   │   └── recommendation/
│   │       ├── base.py                # RecommendationStrategy (ABC)
│   │       ├── engine.py              # RecommendationEngine (Strategy context)
│   │       ├── popularity.py          # Sort songs by play count
│   │       ├── content_based.py       # Match user's genre/artist preferences
│   │       └── collaborative.py       # Jaccard-similarity user-based CF
│   │
│   ├── cache/
│   │   └── redis_cache.py             # CacheManager (get/set/invalidate/flush)
│   │
│   ├── middleware/
│   │   └── rate_limiter.py            # TokenBucket + RateLimiterMiddleware
│   │
│   ├── notifications/
│   │   ├── observer.py                # EventType, Observer (ABC), EventManager
│   │   ├── email_notifier.py          # EmailNotifier (Observer impl.)
│   │   └── push_notifier.py           # PushNotifier (Observer impl.)
│   │
│   └── routes/
│       ├── playlist_routes.py         # /playlists endpoints
│       └── recommendation_routes.py   # /recommendations + /songs endpoints
│
├── static/
│   ├── index.html                     # Frontend SPA
│   ├── styles.css                     # UI styles
│   └── app.js                         # Frontend logic
│
├── tests/
│   ├── test_playlists.py              # Playlist CRUD tests
│   ├── test_recommendations.py        # Strategy & engine tests
│   ├── test_cache.py                  # Cache hit/miss/invalidation tests
│   └── test_rate_limiter.py           # Token bucket tests
│
├── requirements.txt
└── README.md

---

🚀 Quick Start

1. Clone the repository

git clone https://github.com/not-shivansh/Playlist-Recommendation-Service-API-FastAPI-Redis-System-Design-Project.git
cd "Playlist-Recommendation-Service-API-FastAPI-Redis-System-Design-Project"

2. Create a virtual environment

python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Run the server

uvicorn app.main:app --reload --port 8000

5. Explore

URL	Description
http://localhost:8000	Frontend UI
http://localhost:8000/docs	Swagger / Interactive API Docs
http://localhost:8000/redoc	ReDoc API Reference
http://localhost:8000/health	Health check

Note: The project uses fakeredis by default — no Redis server required. To use a real Redis instance, set USE_FAKE_REDIS = False and configure REDIS_URL in app/config.py.

---

📝 API Reference

Playlists

Method	Endpoint	Description
POST	/playlists	Create a new playlist
GET	/playlists	List all playlists
GET	/playlists/{id}	Get a playlist by ID
PUT	/playlists/{id}	Update playlist name
DELETE	/playlists/{id}	Delete a playlist
POST	/playlists/{id}/songs/{song_id}	Add a song to a playlist
DELETE	/playlists/{id}/songs/{song_id}	Remove a song from a playlist

Create Playlist — Request Body:

{
  "name": "My Chill Mix",
  "user_id": "user_42"
}

---

Recommendations

Method	Endpoint	Description
GET	/recommendations	Get recommendations with chosen strategy
GET	/recommendations/personalized	Personalized content-based recommendations

Query Parameters for /recommendations:

Parameter	Type	Default	Description
user_id	string	required	User to generate recommendations for
strategy	string	popularity	One of: popularity, content_based, collaborative
n	int	10	Number of songs to return (1–50)

Example:

curl "http://localhost:8000/recommendations?user_id=alice&strategy=collaborative&n=5"

---

Songs

Method	Endpoint	Description
GET	/songs	Browse the full song catalog
GET	/songs?genre=Rock	Filter songs by genre

---

System

Method	Endpoint	Description
GET	/	Serves the frontend SPA
GET	/health	Returns {"status": "healthy"}

---

Unified API Response Format

All endpoints return a consistent envelope:

{
  "success": true,
  "message": "Recommendations (collaborative)",
  "data": [ ... ]
}

On errors:

{
  "success": false,
  "message": "Rate limit exceeded. Try again later.",
  "data": null
}

---

🔒 Rate Limiting

Pass X-User-Id header to identify users. Without it, requests are bucketed by IP.

curl -H "X-User-Id: alice" http://localhost:8000/recommendations?user_id=alice

Response headers on every request:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97

When the bucket is exhausted:

HTTP 429 Too Many Requests
Retry-After: 60

---

🧪 Running Tests

pytest tests/ -v

Test coverage:

• test_playlists.py — CRUD operations, song management
• test_recommendations.py — All three strategies, strategy switching
• test_cache.py — Cache hit/miss, TTL, invalidation, flush
• test_rate_limiter.py — Token consumption and 429 enforcement

---

🛠️ Tech Stack

Layer	Technology
Web Framework	FastAPI 0.115 — async, OpenAPI-first
ASGI Server	Uvicorn 0.30
ORM	SQLAlchemy 2.0 — async-compatible, declarative models
Validation	Pydantic v2 — strict schema validation
Database	SQLite — zero-config, file-based
Cache	fakeredis 2.24 — Redis-compatible, in-process (no infra needed)
Testing	pytest 8.3 + httpx 0.27 (async test client)

---

⚙️ Configuration

All tunable parameters live in app/config.py:

USE_FAKE_REDIS       = True          # False → connect to real Redis
REDIS_URL            = "redis://localhost:6379/0"
CACHE_TTL_SECONDS    = 600           # 10-minute cache TTL
RATE_LIMIT_CAPACITY  = 100           # token bucket size
RATE_LIMIT_WINDOW_SECONDS = 60       # refill window
DATABASE_URL         = "sqlite:///playlist_service.db"

---

🗺️ Future Enhancements

• JWT / OAuth2 authentication
• Real Redis with persistence and Pub/Sub
• WebSocket real-time notifications
• ML-powered recommendation engine (matrix factorization)
• Docker + Docker Compose setup
• PostgreSQL migration guide
• Deployment on AWS / GCP / Railway

---

Author

This project is open-source. Shivansh Thakur.

---

Built as a System Design project demonstrating scalable backend architecture patterns
Strategy · Observer · Repository · Cache-Aside · Token Bucket