How srichandra30/harmonia works
Harmonia is a music-streaming product with a React client, an Express API, and a separate FastAPI recommendation service. A typical listener browses or searches for music, selects tracks for playback, and manages a library or playlists; the platform also supports accounts, artist uploads, charts, moderation, and personalized recommendations. The graph highlights those product stages and the ML indexing/recommendation layer. Source excerpts are partial, so some subsystem links follow the documented API/service boundaries rather than inspected call sites.
Main entry points: v1 API routes · models Music and user records · main.py FastAPI service · index.js Express API
Components 26
Listener experience
- Web app
frontend/src/App.jsx - API client
frontend/src/services/apiClient.js - Player UI
frontend/src/components/Player/Player.jsx
Platform API
- Express API
backend/src/index.js - API routes
backend/src/routes/v1
Music catalog
- Track endpoints
backend/src/controllers/trackController.js - Search endpoints
backend/src/controllers/searchController.js - Jamendo integration
backend/src/services/JamendoService.js - Artist uploads
backend/src/controllers/artistUploadController.js
Accounts and listening
- Auth endpoints
backend/src/controllers/authController.js - Playlists
backend/src/controllers/playlistController.js - Library
backend/src/controllers/libraryController.js - Recommendations
backend/src/controllers/recommendationController.js - Recommendation logic
backend/src/services/RecommendationService.js - Music and user records
backend/src/models
Recommendation service
- FastAPI service
ml_service/app/main.py - Recommendation endpoint
ml_service/app/routers/recommendations.py - Hybrid recommender
ml_service/app/models/recommender.py - Track ingestion
ml_service/app/services/track_ingestion.py - CLAP embedder
ml_service/app/services/pretrained_clap_embedder.py - FAISS index
ml_service/app/models/faiss_index.py - Interaction store
ml_service/app/services/interaction_store.py
Other components
- Listener
- MongoDB
- Redis
- Jamendo API
Connections 34
- Listener → Web app: uses
- Web app → API client: requests data
- Web app → Player UI: controls playback
- API client → Express API: HTTP requests
- Express API → API routes: dispatches
- API routes → Auth endpoints: dispatches auth
- API routes → Track endpoints: dispatches tracks
- API routes → Search endpoints: dispatches search
- API routes → Artist uploads: dispatches uploads
- API routes → Playlists: dispatches playlists
- API routes → Library: dispatches library
- API routes → Recommendations: dispatches recommendations
- Track endpoints → Music and user records: reads and updates
- Track endpoints → Jamendo integration: fetches tracks
- Search endpoints → Music and user records: searches catalog
- Artist uploads → Music and user records: creates tracks
- Playlists → Music and user records: reads and writes
- Library → Music and user records: reads and writes
- Auth endpoints → Music and user records: reads and writes
- Recommendations → Recommendation logic: requests recommendations
- Recommendations → Jamendo integration: fetches fallback tracks
- Music and user records → MongoDB: persists records
- Express API → MongoDB: connects
- Express API → Redis: initializes
- FastAPI service → Recommendation endpoint: serves endpoints
- FastAPI service → Hybrid recommender: initializes
- FastAPI service → Interaction store: connects and configures
- FastAPI service → Track ingestion: starts ingestion
- Recommendation endpoint → Hybrid recommender: gets recommendations
- Track ingestion → MongoDB: reads new tracks
- Track ingestion → CLAP embedder: generates embeddings
- Track ingestion → FAISS index: adds vectors
- Hybrid recommender → FAISS index: searches vectors
- Jamendo integration → Jamendo API: fetches catalog