# zona05/spotify-dynamic-list architecture

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

- Interactive diagram: https://gitdiagram.com/zona05/spotify-dynamic-list
- Repository: https://github.com/zona05/spotify-dynamic-list

## Overview

##### Main Components
- Spotify API Integration & Authentication: The script (SpotifyDynamic.py) handles OAuth-based authentication to securely connect with Spotify.
- Data Management: Two JSON files (canciones_favoritas.json and generos_filtrados.json) serve as local storage for the user’s favorite songs and for filtered genres (those with at least 10 songs).
- Playlist Management Logic: Within SpotifyDynamic.py, this logic selects a random valid genre, checks whether a “Dynamic Playlist” exists, and creates or updates it accordingly.
- Scheduled Automation: The GitHub Actions workflow (.github/workflows/main.yml) is responsible for triggering the script daily at midnight (UTC).
- Dependencies and Environment Setup: The requirements.txt file specifies the necessary packages, ensuring the environment is set up correctly to run the script.

##### Out the Relationships and Interactions
- The “User / Client” provides necessary Spotify credentials (configured on the Spotify Developer Dashboard) which are used by the OAuth authentication flow.
- The “SpotifyDynamic.py” script:
- Initiates with OAuth authentication.
- Reads the local JSON files to gather data about favorite songs and genre counts.
- Calls the Spotify API to fetch/update the playlist based on the selected random genre.
- Data flows:
- From the JSON files to the script’s processing logic.
- From the script to Spotify via API calls for playlist creation/updating.
- The GitHub Actions workflow triggers the script automatically, simulating a “scheduler” that executes the logic on a daily basis.

##### Architectural Pattern and Design Principles
- Even though the project is a relatively straightforward script, it demonstrates a separation of concerns by isolating API authentication, data management, and playlist handling.
- It also follows practices for automation, ensuring regular updates via CI/CD (GitHub Actions).
- The design essentially resembles a microservice or scheduled task with clearly defined input (data in JSON, API credentials) and output (playlist creation/updating via the Spotify API).

##### Elements
- Clear Labels: Name each component (e.g., "OAuth Authentication", "Data Management", "Playlist Manager", "GitHub Actions Scheduler", "Spotify API").

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User / Spotify Account"]:::external
    B["GitHub Actions Scheduler"]:::external
    C["Requirements Setup"]:::env

    subgraph "Dynamic Playlist Script (SpotifyDynamic.py)"
        D["OAuth Authentication"]:::internal
        E["Data Loader"]:::internal
        F["Playlist Manager (Genre Filter & API Client)"]:::internal
    end

    subgraph "Local Data"
        G["canciones_favoritas.json"]:::data
        H["generos_filtrados.json"]:::data
    end

    I["Spotify API"]:::external

    %% Connections
    B -->|"Triggers"| D
    A -->|"ProvidesCredentials"| D
    G -->|"LoadsFavorites"| E
    H -->|"LoadsFilteredGenres"| E
    D -->|"AuthSuccess"| E
    E -->|"SelectsGenre"| F
    F -->|"PlaylistUpdate"| I
    C ---|"Dependencies"| D

    %% Click Events
    click D "https://github.com/zona05/spotify-dynamic-list/blob/main/SpotifyDynamic.py"
    click F "https://github.com/zona05/spotify-dynamic-list/blob/main/SpotifyDynamic.py"
    click G "https://github.com/zona05/spotify-dynamic-list/blob/main/canciones_favoritas.json"
    click H "https://github.com/zona05/spotify-dynamic-list/blob/main/generos_filtrados.json"
    click B "https://github.com/zona05/spotify-dynamic-list/blob/main/.github/workflows/main.yml"
    click C "https://github.com/zona05/spotify-dynamic-list/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#ffefef,stroke:#d33,stroke-width:2px;
    classDef internal fill:#e0f7fa,stroke:#00796b,stroke-width:2px;
    classDef data fill:#f1f8e9,stroke:#8bc34a,stroke-width:2px;
    classDef env fill:#fff3e0,stroke:#fb8c00,stroke-width:2px;
```
