# samaypatel27/spotify-to-karaoke architecture

> Architecture diagram of the GitHub repository samaypatel27/spotify-to-karaoke, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samaypatel27/spotify-to-karaoke
- Repository: https://github.com/samaypatel27/spotify-to-karaoke

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    UserBrowser["User Browser"]:::external

    %% Client Side
    subgraph "React SPA (Client)"
        direction TB
        SPA["React SPA"]:::client
        Public["Public Static Assets"]:::client
        EntryIndex["Index (client/src/index.js)"]:::client
        AppShell["App Shell & Routing (client/src/App.js)"]:::client

        subgraph "Views & Components"
            direction TB
            Home["Home View"]:::client
            Dashboard["Dashboard View"]:::client
            Create["Create Playlist View"]:::client
            ProcessView["Process/Conversion View"]:::client
        end

        subgraph "Context Providers"
            direction TB
            FormContext["FormContext"]:::client
            ThemeContext["ThemeContext"]:::client
        end

        subgraph "Styles"
            direction TB
            AppStyles["Global App Styles"]:::client
            DashboardStyles["Dashboard Styles"]:::client
            HomeStyles["Home Styles"]:::client
        end
    end

    %% Server Side
    subgraph "Flask API (Server)"
        direction TB
        API["Flask App & Controllers"]:::backend
        Extensions["Flask Extensions"]:::backend
        Models["Data Models & Persistence"]:::backend
        SpotifyModule["Spotify OAuth & API Wrapper"]:::backend
    end

    %% External Services
    SpotifyAPI["Spotify API"]:::external
    YouTubeAPI["YouTube Data API"]:::external
    Database["PostgreSQL / SQLite"]:::db

    %% Data Flows
    UserBrowser -->|"Interacts with UI"| SPA
    SPA -->|"HTTP REST Calls (port 3000→5000)"| API

    API -->|"Uses Extensions"| Extensions
    API -->|"Calls Data Layer"| Models
    API -->|"Invokes OAuth & Sync"| SpotifyModule
    API -->|"Creates YouTube Playlists"| YouTubeAPI
    API -->|"CRUD Operations"| Database
    SpotifyModule -->|"OAuth2 Token Exchange"| SpotifyAPI

    %% Click Events
    click SPA "https://github.com/samaypatel27/spotify-to-karaoke/tree/main/client/"
    click Public "https://github.com/samaypatel27/spotify-to-karaoke/tree/main/client/public/"
    click EntryIndex "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/index.js"
    click AppShell "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/App.js"
    click Home "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/components/Home.js"
    click Dashboard "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/components/Dashboard.js"
    click Create "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/components/Create.js"
    click ProcessView "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/components/Process.js"
    click FormContext "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/context/FormContext.js"
    click ThemeContext "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/context/ThemeContext.js"
    click AppStyles "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/styles/app.module.css"
    click DashboardStyles "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/styles/dashboard.module.css"
    click HomeStyles "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/client/src/styles/home.module.css"
    click API "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/server/app.py"
    click Extensions "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/server/extensions.py"
    click Models "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/server/models.py"
    click SpotifyModule "https://github.com/samaypatel27/spotify-to-karaoke/blob/main/server/spotify.py"

    %% Styles
    classDef client fill:#e0f7ff,stroke:#333,stroke-width:1px
    classDef backend fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef external fill:#ffffcc,stroke:#333,stroke-width:1px
    classDef db fill:#ffe0b2,stroke:#333,stroke-width:1px
```
