# sushanttusharjoshi/ai-playlist-mixer architecture

> Architecture diagram of the GitHub repository sushanttusharjoshi/ai-playlist-mixer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sushanttusharjoshi/ai-playlist-mixer
- Repository: https://github.com/sushanttusharjoshi/ai-playlist-mixer

## Overview

1. **Overall shape**
   - This is a two-tier application: a **Next.js frontend** in `frontend/` and a **Python backend API** in `backend/`.
   - The product is centered on a “playlist mixer” workflow with three user roles: **landing/join**, **host**, **party guest**, plus an **admin/insights** view.

2. **Frontend boundary**
   - The frontend uses the **Next.js App Router** structure under `frontend/app/`.
   - Key route surfaces are:
     - `/` for creating or joining a session
     - `/host/[code]` for the host dashboard
     - `/party/[code]` for guest participation
     - `/admin/[code]` for ML/analytics insights
   - `frontend/lib/api.ts` is the main client-side boundary to the backend, so the UI likely talks to the API through one centralized wrapper.

3. **Backend entrypoint and runtime**
   - `backend/app/main.py` is the service entrypoint, and the README shows it runs as a **FastAPI** app via `uvicorn`.
   - Production deployment is designed for a standard Python web service runtime, with `gunicorn` + `uvicorn.workers.UvicornWorker` on Render.
   - The backend is therefore the authoritative place for session logic, ranking logic, and third-party integrations.

4. **Core domain subsystem: agents**
   - `backend/app/agents/` is the main business-logic layer.
   - The presence of `ranking_agent.py`, `voting_agent.py`, `fairness_agent.py`, `profile_agent.py`, and `llm_agent.py` suggests the app uses multiple specialized decision modules rather than one monolithic recommender.
   - Architecturally, this is where the system likely turns user votes, participant profiles, and track metadata into playlist ordering and explanations.

5. **ML / feature engineering layer**
   - `backend/app/ml/features.py` indicates a separate feature-extraction layer feeding the agents or analytics.
   - This is a distinct boundary from the agent logic: raw data is transformed into derived attributes before ranking or clustering-style insights are produced.
   - The `/admin` route in the frontend likely visualizes outputs from this ML layer.

6. **External music/video integrations**
   - `backend/app/services/spotify.py`, `spotify_search.py`, and `youtube.py` are the integration adapters.
   - Spotify is the primary external music platform, with search and likely playback or metadata operations split into separate modules.
   - YouTube support suggests fallback or enrichment for tracks/videos when Spotify data is insufficient or when a track needs alternate media lookup.

7. **Models and API contracts**
   - `backend/app/models/schemas.py` defines the request/response shapes used by the API.
   - This is the contract boundary between frontend and backend, and also between backend subsystems if they exchange structured objects.
   - The use of schema models implies typed payloads and explicit validation at the API layer.

8. **Shared data/state layer**
   - `backend/app/data.py` is likely the shared in-process data source for rooms, votes, or playlist state.
   - There is no obvious database directory in the tree, so the architecture does not show a dedicated persistence subsystem.
   - For diagramming, treat state handling as a backend concern, with persistence either minimal, external, or embedded elsewhere not visible in the tree.

9. **Configuration and environment**
   - `backend/app/config.py` centralizes environment-driven configuration.
   - The README explicitly calls out Spotify credentials, a Claude key, `FRONTEND_URL`, and a Spotify callback URL, so the backend is designed around external-service configuration rather than local defaults.
   - The system depends on OAuth/API credentials for runtime behavior.

10. **Role-based user flows**
   - The frontend routes map cleanly to backend capabilities:
     - **Guest flow**: join a session, search, vote
     - **Host flow**: manage queue and playback, review search and votes
     - **Admin flow**: inspect clusters, scores, and scoring formula outputs
   - This role split is a useful architectural boundary: UI concerns are separated by role, while the backend services remain shared.

11. **AI/LLM usage boundary**
   - The presence of `llm_agent.py` and the README reference to a Claude key show that generative AI is part of the backend decision layer.
   - This is likely used for explanations, recommendations, or synthesis of playlist decisions rather than direct UI rendering.
   - In a diagram, it should sit alongside the ranking/fairness agents as an external-AI-backed subsystem.

12. **Deployment topology**
   - The intended production setup is:
     - **Frontend** on Vercel
     - **Backend** on Render
     - Spotify callback routed to the backend
   - `NEXT_PUBLIC_API_BASE` connects the browser app to the backend service, making the frontend a thin presentation layer over the API.

13. **What is notably absent**
   - No database, message queue, cache, or worker directory is visible.
   - That means the repository, as shown, is primarily a **single API service + UI client** with external API integrations and local business logic, rather than a distributed backend platform.

14. **Recommended architecture diagram framing**
   - Draw three main boxes:
     - **Browser / Next.js UI**
     - **Python API backend**
     - **External services**: Spotify, YouTube, Claude
   - Inside the backend box, show four sublayers: **API entrypoint**, **domain agents**, **feature/ML utilities**, and **service adapters**.
   - Connect the frontend to the backend through `lib/api.ts`, and connect the backend outward to Spotify/YouTube/Claude via the service and agent subsystems.

Main entry points: [`backend/app/main.py`](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/main.py) (FastAPI app), [`frontend/lib/api.ts`](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/lib/api.ts) (API client), [`backend/app/agents/ranking_agent.py`](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/ranking_agent.py) (Ranking agent), [`backend/app/services/spotify.py`](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/services/spotify.py) (Spotify adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_home["Join room<br/>Next.js route<br/>[page.tsx]"]
  node_frontend_host["Host view<br/>Next.js route<br/>[page.tsx]"]
  node_frontend_party["Guest view<br/>Next.js route<br/>[page.tsx]"]
  node_frontend_admin["Admin view<br/>Next.js route<br/>[page.tsx]"]
  node_frontend_api["API client<br/>client wrapper<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>service entrypoint<br/>[main.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_state[("Room state<br/>shared state<br/>[data.py]")]
  node_backend_schemas["Schemas<br/>API contracts<br/>[schemas.py]"]
  node_backend_ranking["Ranking agent<br/>decision logic<br/>[ranking_agent.py]"]
  node_backend_voting["Voting agent<br/>decision logic<br/>[voting_agent.py]"]
  node_backend_fairness["Fairness agent<br/>decision logic<br/>[fairness_agent.py]"]
  node_backend_profile["Profile agent<br/>decision logic<br/>[profile_agent.py]"]
  node_backend_llm["LLM agent<br/>ai synthesis<br/>[llm_agent.py]"]
  node_backend_features["Feature engine<br/>ml features<br/>[features.py]"]
  node_backend_spotify["Spotify adapter<br/>integration<br/>[spotify.py]"]
  node_backend_search["Search adapter<br/>integration<br/>[spotify_search.py]"]
  node_backend_youtube["YouTube adapter<br/>integration<br/>[youtube.py]"]
end

subgraph group_external["External services"]
  node_ext_spotify(("Spotify<br/>external platform"))
  node_ext_youtube(("YouTube<br/>external platform"))
  node_ext_claude(("Claude<br/>external AI"))
end

node_frontend_home -->|"join/create"| node_frontend_api
node_frontend_host -->|"manage room"| node_frontend_api
node_frontend_party -->|"search/vote"| node_frontend_api
node_frontend_admin -->|"insights"| node_frontend_api
node_frontend_api -->|"HTTP API"| node_backend_main
node_backend_main -->|"validates"| node_backend_schemas
node_backend_main -->|"reads/writes"| node_backend_state
node_backend_main -->|"orchestrates"| node_backend_ranking
node_backend_main -->|"orchestrates"| node_backend_voting
node_backend_main -->|"orchestrates"| node_backend_profile
node_backend_main -->|"orchestrates"| node_backend_fairness
node_backend_main -->|"orchestrates"| node_backend_llm
node_backend_main -->|"derives"| node_backend_features
node_backend_ranking -->|"uses"| node_backend_features
node_backend_profile -->|"uses"| node_backend_features
node_backend_voting -->|"updates"| node_backend_state
node_backend_ranking -->|"tracks"| node_backend_spotify
node_backend_search -->|"searches"| node_backend_spotify
node_backend_youtube -->|"calls"| node_ext_youtube
node_backend_spotify -->|"calls"| node_ext_spotify
node_backend_llm -->|"calls"| node_ext_claude

click node_frontend_home "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/app/page.tsx"
click node_frontend_host "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/app/host/[code]/page.tsx"
click node_frontend_party "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/app/party/[code]/page.tsx"
click node_frontend_admin "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/app/admin/[code]/page.tsx"
click node_frontend_api "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/lib/api.ts"
click node_backend_main "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/main.py"
click node_backend_config "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/config.py"
click node_backend_state "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/data.py"
click node_backend_schemas "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/models/schemas.py"
click node_backend_ranking "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/ranking_agent.py"
click node_backend_voting "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/voting_agent.py"
click node_backend_fairness "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/fairness_agent.py"
click node_backend_profile "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/profile_agent.py"
click node_backend_llm "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/llm_agent.py"
click node_backend_features "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/ml/features.py"
click node_backend_spotify "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/services/spotify.py"
click node_backend_search "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/services/spotify_search.py"
click node_backend_youtube "https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/services/youtube.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_frontend_home,node_frontend_host,node_frontend_party,node_frontend_admin,node_frontend_api toneBlue
class node_backend_main,node_backend_config,node_backend_state,node_backend_schemas,node_backend_ranking,node_backend_voting,node_backend_fairness,node_backend_profile,node_backend_llm,node_backend_features,node_backend_spotify,node_backend_search,node_backend_youtube toneAmber
class node_ext_spotify,node_ext_youtube,node_ext_claude toneMint
```

## Components

### Frontend

Next.js App Router UI for landing, host, guest, and admin flows.

- [Join room](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/app/page.tsx): Next.js route · Landing page for creating or joining a playlist session. · `frontend/app/page.tsx`
- [Host view](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/app/host/[code]/page.tsx): Next.js route · Host dashboard for managing the room and playlist flow. · `frontend/app/host/[code]/page.tsx`
- [Guest view](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/app/party/[code]/page.tsx): Next.js route · Guest participation screen for searching and voting. · `frontend/app/party/[code]/page.tsx`
- [Admin view](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/app/admin/[code]/page.tsx): Next.js route · Analytics and ML insights surface for a session. · `frontend/app/admin/[code]/page.tsx`
- [API client](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/frontend/lib/api.ts): client wrapper · Central frontend boundary for calling the backend API. · `frontend/lib/api.ts`

### Backend

FastAPI service with session logic, ranking, ML, and integrations.

- [FastAPI app](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/main.py): service entrypoint · Backend application entrypoint served by uvicorn/gunicorn. · `backend/app/main.py`
- [Config](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/config.py): runtime config · Environment-driven settings and service credentials. · `backend/app/config.py`
- [Room state](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/data.py): shared state · In-process session, vote, and playlist state management. · `backend/app/data.py`
- [Schemas](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/models/schemas.py): API contracts · Request and response models shared across API boundaries. · `backend/app/models/schemas.py`
- [Ranking agent](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/ranking_agent.py): decision logic · Orders tracks using votes, profiles, fairness, and metadata. · `backend/app/agents/ranking_agent.py`
- [Voting agent](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/voting_agent.py): decision logic · Processes guest votes and voting-related rules. · `backend/app/agents/voting_agent.py`
- [Fairness agent](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/fairness_agent.py): decision logic · Balances playlist outcomes across participants and preferences. · `backend/app/agents/fairness_agent.py`
- [Profile agent](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/profile_agent.py): decision logic · Derives participant profiles and preference signals. · `backend/app/agents/profile_agent.py`
- [LLM agent](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/agents/llm_agent.py): ai synthesis · Generative AI layer for explanations or higher-level recommendations. · `backend/app/agents/llm_agent.py`
- [Feature engine](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/ml/features.py): ml features · Transforms raw track and session data into derived features. · `backend/app/ml/features.py`
- [Spotify adapter](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/services/spotify.py): integration · Primary adapter for Spotify metadata and related operations. · `backend/app/services/spotify.py`
- [Search adapter](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/services/spotify_search.py): integration · Spotify search-specific service boundary. · `backend/app/services/spotify_search.py`
- [YouTube adapter](https://github.com/sushanttusharjoshi/ai-playlist-mixer/blob/main/backend/app/services/youtube.py): integration · Fallback or enrichment adapter for video/media lookup. · `backend/app/services/youtube.py`

### External services

Third-party platforms used by the backend.

- **Spotify**: external platform · External music service used for search and metadata.
- **YouTube**: external platform · External media platform used for alternate lookup or enrichment.
- **Claude**: external AI · LLM provider used by the backend AI layer.

## Connections

- Join room → API client: join/create · Creates or joins a playlist session through the API client.
- Host view → API client: manage room · Host actions are routed through the shared API wrapper.
- Guest view → API client: search/vote · Guest interactions call the backend through the API wrapper.
- Admin view → API client: insights · Admin analytics requests go through the same client boundary.
- API client → FastAPI app: HTTP API · Frontend talks to the FastAPI backend as the core service.
- FastAPI app → Schemas: validates · API endpoints use typed request and response contracts.
- FastAPI app → Room state: reads/writes · Session flow depends on shared room and vote state.
- FastAPI app → Ranking agent: orchestrates · API calls trigger ranking and playlist ordering logic.
- FastAPI app → Voting agent: orchestrates · Vote submission and tallying are handled by domain logic.
- FastAPI app → Profile agent: orchestrates · Participant profile derivation supports session decisions.
- FastAPI app → Fairness agent: orchestrates · Fairness logic participates in playlist and scoring decisions.
- FastAPI app → LLM agent: orchestrates · AI-backed explanations or synthesis are exposed through the API.
- FastAPI app → Feature engine: derives · Feature extraction feeds ranking and analytics paths.
- Ranking agent → Feature engine: uses · Ranking consumes engineered features.
- Profile agent → Feature engine: uses · Profile building relies on derived features.
- Voting agent → Room state: updates · Voting changes shared session state.
- Ranking agent → Spotify adapter: tracks · Ranking and metadata logic interact with Spotify data.
- Search adapter → Spotify adapter: searches · Search adapter delegates to Spotify.
- YouTube adapter → YouTube: calls · YouTube integration reaches the external platform.
- Spotify adapter → Spotify: calls · Spotify adapter reaches the external music service.
- LLM agent → Claude: calls · LLM agent uses the Claude provider for generative tasks.