# sharmaaarush/spotify-billboard-playlist architecture

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

- Interactive diagram: https://gitdiagram.com/sharmaaarush/spotify-billboard-playlist
- Repository: https://github.com/sharmaaarush/spotify-billboard-playlist

## Overview

##### Project Type and Purpose
- This is a standalone Python desktop application with a simple GUI that scrapes Billboard’s Hot 100 for a user-entered date and then uses the Spotify Web API to build a private playlist in the user’s account.
- Key functions:
– Collect a date via GUI (tkinter)
– Scrape Billboard chart (BeautifulSoup)
– Authenticate with Spotify and manage tokens (requests + python-dotenv)
– Search tracks, create playlist, add tracks (Spotify Web API)

##### File Structure and Roles
- .env – environment variables for Spotify credentials (CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, ACCESS_TOKEN, REFRESH_TOKEN, USER_ID)
- api_setup.py – handles OAuth flow, token refresh, and wraps Spotify API calls:
· get_access_token()
· create_playlist()
· search_track()
· add_tracks_to_playlist()
- main.py – GUI orchestration, ties together:
· Date input & button event (tkinter)
· Billboard scraping (BeautifulSoup)
· Spotify workflow (calls api_setup functions)
· Outputs playlist link to user
- README.md, LICENSE – documentation and licensing

##### Main Architectural Components
A. User Interface Layer
– tkinter window, date input field, “Create Playlist” button
B. Application Logic Layer
– Scraper sub-component (BeautifulSoup)
– Spotify Client sub-component (api_setup.py)
C. Configuration
– .env loader (python-dotenv) providing credentials to Spotify Client
D. External Systems
– Billboard website (HTML pages to scrape)
– Spotify Web API (OAuth 2.0 endpoints and data endpoints)

##### Component Interactions and Data Flow
1) User enters date → clicks button in UI
2) UI triggers Scraper → GET request to Billboard → parse top 100 song titles
3) UI invokes Spotify Client
a) Load .env → retrieve CLIENT_ID/SECRET, tokens
b) If needed, refresh access token via OAuth endpoint
c) For each song title → call search track endpoint → collect track URIs
d) Call create playlist endpoint → receive new playlist ID
e) Call add tracks endpoint with URIs → playlist populated
4) Spotify Client returns playlist URL → UI displays in console

##### Architectural Patterns and Principles
- Separation of concerns: GUI code (main.py) vs. API code (api_setup.py) vs. scrapers vs. config
- One‐process, event‐driven flow: user event triggers sequential tasks

##### Technologies and Frameworks to Annotate
- Python 3.x
- tkinter (UI)
- BeautifulSoup4 + requests (scraping)
- python-dotenv (config)
- Spotify Web API (OAuth 2.0 + REST endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors and Layers
    User["User"]    
    subgraph "Client Application"
        UI["UI (tkinter)"]:::ui
        Scraper["Scraper (BeautifulSoup + requests)"]:::logic
        SpotifyClient["Spotify Client (api_setup.py)"]:::logic
    end
    subgraph "Configuration"
        Env[".env loader"]:::config
    end
    subgraph "External Services"
        Billboard["Billboard Website"]:::external
        SpotifyAPI["Spotify Web API"]:::external
    end

    %% Data Flow
    User -->|"date input"| UI
    UI -->|"date"| Scraper
    Scraper -->|"GETrequest"| Billboard
    Billboard -->|"HTMLresponse"| Scraper
    UI -->|"startWorkflow"| SpotifyClient
    SpotifyClient -->|"loadCredentials"| Env
    Env -->|"CLIENT_ID/SECRET+tokens"| SpotifyClient
    SpotifyClient -->|"refreshTokenRequest"| SpotifyAPI
    SpotifyAPI -->|"newAccessToken"| SpotifyClient
    SpotifyClient -->|"searchTrack(title)"| SpotifyAPI
    SpotifyAPI -->|"trackURIs"| SpotifyClient
    SpotifyClient -->|"createPlaylist"| SpotifyAPI
    SpotifyAPI -->|"playlistID"| SpotifyClient
    SpotifyClient -->|"addTracks(URIs)"| SpotifyAPI
    SpotifyAPI -->|"confirmation"| SpotifyClient
    SpotifyClient -->|"playlistURL"| UI

    %% Click Events
    click UI "https://github.com/sharmaaarush/spotify-billboard-playlist/blob/main/main.py"
    click Scraper "https://github.com/sharmaaarush/spotify-billboard-playlist/blob/main/main.py"
    click SpotifyClient "https://github.com/sharmaaarush/spotify-billboard-playlist/blob/main/api_setup.py"
    click Env "https://github.com/sharmaaarush/spotify-billboard-playlist/blob/main/.env"
    click README["README.md"] "README.md"
    click LICENSE["LICENSE"] "LICENSE"

    %% Styles
    classDef ui fill:#8fbc8f,stroke:#333,stroke-width:1px
    classDef logic fill:#add8e6,stroke:#333,stroke-width:1px
    classDef config fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
```
