rec_o

rec_o is a music recommendation system built as a final project during a 2-week data science bootcamp- then extended independently after the bootcamp ended. It combines KNN-based machine learning models with real-time data from ListenBrainz and a self-hosted mirror of the MusicBrainz database to generate personalized artist and album recommendations.

The project is split across three repositories:

• rec_o – FastAPI backend, ML training pipeline, and GCP deployment
• rec_o-next – Next.js production frontend, live at rec-o-next.vercel.app
• rec_o-front – Initial Streamlit prototype, archived after the Next.js migration

Project presentation (in French 🇫🇷)

Tech Stack

Layer	Technologies
Backend API	FastAPI, Uvicorn, Pydantic, slowapi
Machine Learning	Scikit-learn (KNN), Pandas, NumPy, SciPy, Joblib, cld3-py
Database	PostgreSQL (MusicBrainz mirror, psycopg)
Storage	Google Cloud Storage (model artifacts)
Infrastructure	Google Compute Engine, Cloud Run, Docker, Cloud Build
External APIs	ListenBrainz API, ntfy
Frontend	Next.js 16, React 19, TypeScript 5, Tailwind CSS 4
Deployment	Vercel (frontend), Cloud Run (backend)

What I Did

I was project owner for the full duration of the bootcamp and continued developing the project independently afterward.

Project Setup and Infrastructure

• Created and configured a Google Compute Engine VM and used Docker to deploy a full MusicBrainz database mirror, which serves as the core data source for all recommendations
• Set up remote access to the PostgreSQL instance and identified the most useful tables and columns for the recommendation tasks
• Initialized both backend and frontend Git repositories and set up the Kanban board for task tracking
• Defined all API routes with their request payloads, response shapes, and parameters
• Locked the main branch and reviewed pull requests before merging to maintain codebase stability

Machine Learning and Data

• Built the release group (album) KNN model end-to-end: data queries, feature engineering, training pipeline, and serialization to .pkl
• Updated preprocessing to use scikit-learn pipelines and incorporated more data including language and script detection via cld3-py for album titles and tracks
• Created the predict_artist function that queries the MusicBrainz DB from a model-predicted list of artist IDs
• Iterated from a baseline album model to a slimmer, faster version
• Integrated the album model into the FastAPI backend and wired it to the API response layer

Backend and Integrations

• Implemented the ListenBrainz API integration: calling the API, handling token authentication, resolving returned MBIDs to internal MusicBrainz artist and release_group IDs, and creating the /api/listenbrainz/artist and /api/listenbrainz/album routes
• Implemented the ntfy notification integration so users receive real-time push notifications when recommendations are ready
• Deployed the backend to Google Cloud Run with CI/CD via cloudbuild.yaml and secrets managed through GCP Secret Manager

Frontend

• Led the migration from Streamlit to Next.js after the bootcamp, rebuilding the UI in TypeScript with React 19 and Tailwind CSS 4
• Designed and implemented the modern retro visual style with full dark and light theme support
• Built the dual-input UX: manual search mode and ListenBrainz profile mode, with blacklist support and MusicBrainz deep links
• Integrated ntfy notification options directly into the frontend recommendation flow
• Deployed the frontend to Vercel

Leadership and Delivery

• Defined every task’s priority at the start of the project and maintained the overall roadmap throughout the two weeks
• Helped build the product vision and guided teammates through the MusicBrainz database schema, API contracts, and model behavior
• Prepared and delivered the final presentation of the project to the bootcamp

Team

Built during a data science bootcamp with @ThomasIsHere, @cherguia, and @BenJ676.