How sushanttusharjoshi/ai-playlist-mixer works
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: main.py FastAPI app · api.ts API client · ranking_agent.py Ranking agent · spotify.py Spotify adapter
Components 21
Frontend
Next.js App Router UI for landing, host, guest, and admin flows.
- Join room · Landing page for creating or joining a playlist session.
frontend/app/page.tsx - Host view · Host dashboard for managing the room and playlist flow.
frontend/app/host/[code]/page.tsx - Guest view · Guest participation screen for searching and voting.
frontend/app/party/[code]/page.tsx - Admin view · Analytics and ML insights surface for a session.
frontend/app/admin/[code]/page.tsx - API client · Central frontend boundary for calling the backend API.
frontend/lib/api.ts
Backend
FastAPI service with session logic, ranking, ML, and integrations.
- FastAPI app · Backend application entrypoint served by uvicorn/gunicorn.
backend/app/main.py - Config · Environment-driven settings and service credentials.
backend/app/config.py - Room state · In-process session, vote, and playlist state management.
backend/app/data.py - Schemas · Request and response models shared across API boundaries.
backend/app/models/schemas.py - Ranking agent · Orders tracks using votes, profiles, fairness, and metadata.
backend/app/agents/ranking_agent.py - Voting agent · Processes guest votes and voting-related rules.
backend/app/agents/voting_agent.py - Fairness agent · Balances playlist outcomes across participants and preferences.
backend/app/agents/fairness_agent.py - Profile agent · Derives participant profiles and preference signals.
backend/app/agents/profile_agent.py - LLM agent · Generative AI layer for explanations or higher-level recommendations.
backend/app/agents/llm_agent.py - Feature engine · Transforms raw track and session data into derived features.
backend/app/ml/features.py - Spotify adapter · Primary adapter for Spotify metadata and related operations.
backend/app/services/spotify.py - Search adapter · Spotify search-specific service boundary.
backend/app/services/spotify_search.py - YouTube adapter · Fallback or enrichment adapter for video/media lookup.
backend/app/services/youtube.py
External services
Third-party platforms used by the backend.
- Spotify · External music service used for search and metadata.
- YouTube · External media platform used for alternate lookup or enrichment.
- Claude · LLM provider used by the backend AI layer.
Connections 21
- 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.