How samaypatel27/spotify-to-karaoke works
Project Type and Purpose
• This is a full-stack single-page application whose goal is to let users convert their Spotify playlists into karaoke-style YouTube playlists.
• The front end is a React app (in the client/ directory) that handles UI, OAuth redirects, and REST calls.
• The back end is a Python/Flask monolith (in the server/ directory) that exposes REST endpoints, orchestrates OAuth 2.0 for Spotify & YouTube, persists data via SQLAlchemy, and calls external APIs.
File-Structure Analysis
• Top level splits into client/ (React) and server/ (Flask).
• client/ follows Create-React-App conventions:
• public/ for static HTML/assets
• src/ with components/, context/ (FormContext & ThemeContext for global state), and CSS modules.
• server/ has:
• app.py — Flask app and route definitions
• extensions.py — initialization of SQLAlchemy, CORS, etc.
• models.py — database schema (Users, Playlists, Songs)
• spotify.py — Spotify OAuth and API wrappers
• Configuration & secrets: .env, client_secret.json for YouTube.
• README outlines REST routes for Spotify login/sync, DB queries, and YouTube playlist creation.
Key Architectural Insights from README
• OAuth 2.0 flows for Spotify and YouTube sessions.
• RESTful API design: separate GET/POST endpoints under /spotify, /db, /youtube.
• Database is PostgreSQL (SQLAlchemy ORM), though SQLite compatibility is noted.
• CORS enabled to allow cross-origin calls from localhost:3000.
a. Main Components
• User’s Browser / React SPA
• Flask Backend Service
• Relational Database (PostgreSQL/SQLite)
• External OAuth & Data APIs (Spotify, YouTube Data API)
b. Interactions & Data Flow
1. User navigates React SPA → triggers OAuth login on front end → redirected to Flask endpoints /spotify/login or /youtube/login.
2. Flask handles OAuth handshake → exchanges codes with external API → stores tokens in session → redirects user back to React.
3. React issues REST calls (e.g., POST /spotify/sync) → Flask validates session token → fetches user playlists/tracks from Spotify → persists to DB.
4. React reads DB via GET /db/playlists and GET /db/songs/:playlist_id.
5. When user clicks “Convert,” React calls POST /youtube/playlists with track queries → Flask uses YouTube API to create a new karaoke playlist → returns new playlist link to React.
c. Architectural Patterns & Principles
• Monolithic service for all backend concerns (auth, DB, orchestration).
• RESTful interface separating resource concerns.
• Client-side state management via React Context.
• Layered design: Controllers (Flask routes) → Services (spotify.py) → Data layer (SQLAlchemy).
d. Key Technologies
• Front End: React, React Context API, CSS Modules, Bootstrap (optional)
• Back End: Python, Flask, Flask-CORS, SQLAlchemy ORM, Requests/Spotipy, google-auth libraries
• Database: PostgreSQL (or SQLite for local dev)