# srichandra30/harmonia architecture

> Architecture diagram of the GitHub repository srichandra30/harmonia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/srichandra30/harmonia
- Repository: https://github.com/srichandra30/harmonia

## Overview

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: [`backend/src/routes/v1`](https://github.com/srichandra30/harmonia/tree/main/backend/src/routes/v1) (API routes), [`backend/src/models`](https://github.com/srichandra30/harmonia/tree/main/backend/src/models) (Music and user records), [`ml_service/app/main.py`](https://github.com/srichandra30/harmonia/blob/main/ml_service/app/main.py) (FastAPI service), [`backend/src/index.js`](https://github.com/srichandra30/harmonia/blob/main/backend/src/index.js) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Listener experience"]
  node_web["Web app<br/>[App.jsx]"]
  node_api_client["API client<br/>[apiClient.js]"]
  node_player["Player UI<br/>[Player.jsx]"]
end

subgraph group_api["Platform API"]
  node_backend["Express API<br/>[index.js]"]
  node_routes["API routes"]
end

subgraph group_catalog["Music catalog"]
  node_track_ctrl["Track endpoints<br/>[trackController.js]"]
  node_search_ctrl["Search endpoints"]
  node_jamendo["Jamendo integration<br/>[JamendoService.js]"]
  node_artist_upload["Artist uploads"]
end

subgraph group_personal["Accounts and listening"]
  node_auth_ctrl["Auth endpoints<br/>[authController.js]"]
  node_playlist_ctrl["Playlists"]
  node_library_ctrl["Library"]
  node_recommend_ctrl["Recommendations"]
  node_recommend_service["Recommendation logic"]
  node_mongo_models[("Music and user records")]
end

subgraph group_ml["Recommendation service"]
  node_ml_api["FastAPI service<br/>[main.py]"]
  node_ml_routes["Recommendation endpoint<br/>[recommendations.py]"]
  node_recommender["Hybrid recommender<br/>[recommender.py]"]
  node_indexer["Track ingestion<br/>[track_ingestion.py]"]
  node_embedder["CLAP embedder"]
  node_vector_index[("FAISS index<br/>[faiss_index.py]")]
  node_interaction_store[("Interaction store")]
end

node_listener(("Listener"))
node_mongo[("MongoDB")]
node_redis[("Redis")]
node_jamendo_api["Jamendo API"]

node_listener -->|"uses"| node_web
node_web -->|"requests data"| node_api_client
node_web -->|"controls playback"| node_player
node_api_client -->|"HTTP requests"| node_backend
node_backend -->|"dispatches"| node_routes
node_routes -->|"dispatches auth"| node_auth_ctrl
node_routes -->|"dispatches tracks"| node_track_ctrl
node_routes -->|"dispatches search"| node_search_ctrl
node_routes -->|"dispatches uploads"| node_artist_upload
node_routes -->|"dispatches playlists"| node_playlist_ctrl
node_routes -->|"dispatches library"| node_library_ctrl
node_routes -->|"dispatches recommendations"| node_recommend_ctrl
node_track_ctrl -->|"reads and updates"| node_mongo_models
node_track_ctrl -->|"fetches tracks"| node_jamendo
node_search_ctrl -->|"searches catalog"| node_mongo_models
node_artist_upload -->|"creates tracks"| node_mongo_models
node_playlist_ctrl -->|"reads and writes"| node_mongo_models
node_library_ctrl -->|"reads and writes"| node_mongo_models
node_auth_ctrl -->|"reads and writes"| node_mongo_models
node_recommend_ctrl -->|"requests recommendations"| node_recommend_service
node_recommend_ctrl -->|"fetches fallback tracks"| node_jamendo
node_mongo_models -->|"persists records"| node_mongo
node_backend -->|"connects"| node_mongo
node_backend -->|"initializes"| node_redis
node_ml_api -->|"serves endpoints"| node_ml_routes
node_ml_api -->|"initializes"| node_recommender
node_ml_api -->|"connects and configures"| node_interaction_store
node_ml_api -->|"starts ingestion"| node_indexer
node_ml_routes -->|"gets recommendations"| node_recommender
node_indexer -->|"reads new tracks"| node_mongo
node_indexer -->|"generates embeddings"| node_embedder
node_indexer -->|"adds vectors"| node_vector_index
node_recommender -->|"searches vectors"| node_vector_index
node_jamendo -.->|"fetches catalog"| node_jamendo_api

click node_web "https://github.com/srichandra30/harmonia/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/srichandra30/harmonia/blob/main/frontend/src/services/apiClient.js"
click node_player "https://github.com/srichandra30/harmonia/blob/main/frontend/src/components/Player/Player.jsx"
click node_backend "https://github.com/srichandra30/harmonia/blob/main/backend/src/index.js"
click node_routes "https://github.com/srichandra30/harmonia/tree/main/backend/src/routes/v1"
click node_auth_ctrl "https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/authController.js"
click node_track_ctrl "https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/trackController.js"
click node_search_ctrl "https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/searchController.js"
click node_jamendo "https://github.com/srichandra30/harmonia/blob/main/backend/src/services/JamendoService.js"
click node_artist_upload "https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/artistUploadController.js"
click node_playlist_ctrl "https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/playlistController.js"
click node_library_ctrl "https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/libraryController.js"
click node_recommend_ctrl "https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/recommendationController.js"
click node_recommend_service "https://github.com/srichandra30/harmonia/blob/main/backend/src/services/RecommendationService.js"
click node_mongo_models "https://github.com/srichandra30/harmonia/tree/main/backend/src/models"
click node_ml_api "https://github.com/srichandra30/harmonia/blob/main/ml_service/app/main.py"
click node_ml_routes "https://github.com/srichandra30/harmonia/blob/main/ml_service/app/routers/recommendations.py"
click node_recommender "https://github.com/srichandra30/harmonia/blob/main/ml_service/app/models/recommender.py"
click node_indexer "https://github.com/srichandra30/harmonia/blob/main/ml_service/app/services/track_ingestion.py"
click node_embedder "https://github.com/srichandra30/harmonia/blob/main/ml_service/app/services/pretrained_clap_embedder.py"
click node_vector_index "https://github.com/srichandra30/harmonia/blob/main/ml_service/app/models/faiss_index.py"
click node_interaction_store "https://github.com/srichandra30/harmonia/blob/main/ml_service/app/services/interaction_store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_api_client,node_player toneBlue
class node_backend,node_routes,node_mongo,node_redis toneAmber
class node_track_ctrl,node_search_ctrl,node_jamendo,node_artist_upload,node_jamendo_api toneMint
class node_auth_ctrl,node_playlist_ctrl,node_library_ctrl,node_recommend_ctrl,node_recommend_service,node_mongo_models toneRose
class node_ml_api,node_ml_routes,node_recommender,node_indexer,node_embedder,node_vector_index,node_interaction_store,node_listener toneIndigo
```

## Components

### Listener experience

- [Web app](https://github.com/srichandra30/harmonia/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/srichandra30/harmonia/blob/main/frontend/src/services/apiClient.js): `frontend/src/services/apiClient.js`
- [Player UI](https://github.com/srichandra30/harmonia/blob/main/frontend/src/components/Player/Player.jsx): `frontend/src/components/Player/Player.jsx`

### Platform API

- [Express API](https://github.com/srichandra30/harmonia/blob/main/backend/src/index.js): `backend/src/index.js`
- [API routes](https://github.com/srichandra30/harmonia/tree/main/backend/src/routes/v1): `backend/src/routes/v1`

### Music catalog

- [Track endpoints](https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/trackController.js): `backend/src/controllers/trackController.js`
- [Search endpoints](https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/searchController.js): `backend/src/controllers/searchController.js`
- [Jamendo integration](https://github.com/srichandra30/harmonia/blob/main/backend/src/services/JamendoService.js): `backend/src/services/JamendoService.js`
- [Artist uploads](https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/artistUploadController.js): `backend/src/controllers/artistUploadController.js`

### Accounts and listening

- [Auth endpoints](https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [Playlists](https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/playlistController.js): `backend/src/controllers/playlistController.js`
- [Library](https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/libraryController.js): `backend/src/controllers/libraryController.js`
- [Recommendations](https://github.com/srichandra30/harmonia/blob/main/backend/src/controllers/recommendationController.js): `backend/src/controllers/recommendationController.js`
- [Recommendation logic](https://github.com/srichandra30/harmonia/blob/main/backend/src/services/RecommendationService.js): `backend/src/services/RecommendationService.js`
- [Music and user records](https://github.com/srichandra30/harmonia/tree/main/backend/src/models): `backend/src/models`

### Recommendation service

- [FastAPI service](https://github.com/srichandra30/harmonia/blob/main/ml_service/app/main.py): `ml_service/app/main.py`
- [Recommendation endpoint](https://github.com/srichandra30/harmonia/blob/main/ml_service/app/routers/recommendations.py): `ml_service/app/routers/recommendations.py`
- [Hybrid recommender](https://github.com/srichandra30/harmonia/blob/main/ml_service/app/models/recommender.py): `ml_service/app/models/recommender.py`
- [Track ingestion](https://github.com/srichandra30/harmonia/blob/main/ml_service/app/services/track_ingestion.py): `ml_service/app/services/track_ingestion.py`
- [CLAP embedder](https://github.com/srichandra30/harmonia/blob/main/ml_service/app/services/pretrained_clap_embedder.py): `ml_service/app/services/pretrained_clap_embedder.py`
- [FAISS index](https://github.com/srichandra30/harmonia/blob/main/ml_service/app/models/faiss_index.py): `ml_service/app/models/faiss_index.py`
- [Interaction store](https://github.com/srichandra30/harmonia/blob/main/ml_service/app/services/interaction_store.py): `ml_service/app/services/interaction_store.py`

### Other components

- **Listener**
- **MongoDB**
- **Redis**
- **Jamendo API**

## Connections

- 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