Music Search Engine

A small Spotify-style music catalog search app. It uses Java, Spring Boot, Postgres, Elasticsearch, a local NLP embedding sidecar, and a minimal React frontend.

Services

• backend/api-gateway: public REST API for the frontend.
• backend/catalog-service: Postgres-backed source of truth for artists, albums, tracks, genres, and moods.
• backend/search-service: Elasticsearch indexing, keyword search, autocomplete, query expansion, and vector search.
• backend/embedding-service: FastAPI sidecar that returns text embeddings. Docker uses a lightweight deterministic embedding fallback by default; requirements-ml.txt is included for a later transformer-backed upgrade.
• frontend: minimal React + Vite search UI.

Run Locally

Download the larger Spotify tracks CSV first:

bash scripts/download-spotify-tracks.sh

docker compose -f infrastructure/compose.yaml up --build

Then open:

• Frontend: http://localhost:5173
• API Gateway: http://localhost:8080
• Elasticsearch: http://localhost:9200

If Elasticsearch starts after the search service, trigger indexing again:

curl -X POST http://localhost:8082/admin/reindex

The first version keeps NLP lightweight for easy local startup. To experiment with a real transformer model later, install backend/embedding-service/requirements-ml.txt in that service image/environment.

Dataset

The app imports data/spotify_tracks.csv when it exists. That file is intentionally ignored by git because the public CSV is large. The downloader fetches a GitHub Gist mirror of the Spotify Tracks CSV with columns such as track_id, artists, album_name, track_name, popularity, audio features, and track_genre.

By default the catalog imports the first 5,000 valid CSV rows via CATALOG_CSV_IMPORT_LIMIT. Raise that value in infrastructure/compose.yaml if you want a larger local index.

Elasticsearch

Elasticsearch is used as the search index, while Postgres remains the source of truth for catalog data. The search service reads tracks from the catalog service, converts each track into a denormalized search document, and indexes it into the music_tracks index.

Each indexed track includes title, artist, album, release year, duration, popularity, genres, moods, a combined searchable text field, and a 384-dimension embedding vector. Search combines text matching, metadata boosts, popularity scoring, and vector similarity so results can match both exact terms and looser natural-language intent.

Rebuild the index after changing catalog data:

curl -X POST http://localhost:8082/admin/reindex

NLP

The NLP layer is intentionally lightweight for the first version. The search service expands natural queries with rule-based synonyms and extracts likely genres or moods from phrases such as hiphop with soul beats, bright acoustic love, or dark late night r&b.

The embedding service provides vectors for semantic search. By default it uses a deterministic local fallback, which keeps Docker startup fast and avoids downloading large ML models. A future upgrade can install backend/embedding-service/requirements-ml.txt to use sentence-transformers for stronger semantic embeddings.

Imported CSV audio features also produce mood tags. For example, high danceability can become danceable or groovy, high energy can become energetic, high acousticness can become acoustic or warm, and low valence can become dark or reflective.

Useful Endpoints

curl "http://localhost:8080/api/search?q=hiphop%20with%20soul%20beats"
curl "http://localhost:8080/api/artists?q=kendrick"
curl "http://localhost:8080/api/suggest?q=sou"