# z4no/spotify-in-a-social-way architecture

> Architecture diagram of the GitHub repository z4no/spotify-in-a-social-way, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/z4no/spotify-in-a-social-way
- Repository: https://github.com/z4no/spotify-in-a-social-way

## Overview

##### Project Type and Purpose
- This is a web-based backend service (Flask) that handles Spotify OAuth2 authentication and exposes API endpoints for playlist, track, and player operations.
- It serves as an intermediary between external clients (e.g., a Discord bot or other non-browser apps) and the Spotify API, storing tokens and user data in Firebase.

##### File Structure
- Top-level modules:
- main.py – Flask app entry point
- BaseManager.py, Encripter.py, User.py – core utility classes (DB management, token encryption, user model)
- Subdirectories (Flask Blueprints):
- player/player_operations.py
- playlist/playlist_operations.py
- tracks/tracks_operations.py
- Frontend assets:
- static/ (CSS)
- templates/ (HTML + JS)
- Config & dependencies: requirements.txt, .gitignore, .env expected for client secrets

##### Key Architecture Insights from the README
- OAuth2 flow is web-based: users authenticate via the Flask frontend, which then obtains access & refresh tokens.
- Tokens and collaborative-playlist metadata live in Firebase.
- The service exposes RESTful endpoints to external consumers (Discord bot, CLI, etc.).
- Cryptography module secures sensitive data at rest.

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef external fill:#add8e6,stroke:#000,stroke-width:1px
    classDef service fill:#90ee90,stroke:#000,stroke-width:1px
    classDef db fill:#ffa500,stroke:#000,stroke-width:1px
    classDef api fill:#dda0dd,stroke:#000,stroke-width:1px

    Browser["Web Browser"]:::external
    Client["External Client<br/>(Discord Bot / CLI)"]:::external
    Spotify["Spotify Web API"]:::api
    Firebase["Firebase DB"]:::db

    subgraph "Flask Backend Service"
        direction TB
        main["main.py (Flask App Entry)"]:::service
        subgraph "Blueprints"
            direction TB
            player["Player Operations Blueprint"]:::service
            playlist["Playlist Operations Blueprint"]:::service
            tracks["Tracks Operations Blueprint"]:::service
        end
        subgraph "Utility Modules"
            direction TB
            encrypter["Encripter Module"]:::service
            basemanager["BaseManager Module"]:::service
            user["User Model"]:::service
        end
        subgraph "Frontend UI"
            direction TB
            style1["static/styles/style.css"]:::service
            style2["static/styles/nocredentails.css"]:::service
            html1["templates/index.html"]:::service
            html2["templates/nocredentials.html"]:::service
            js["templates/animations.js"]:::service
        end
    end

    %% OAuth2 Flow
    Browser -->|"/login Auth request"| main
    main -->|"OAuth2 Auth Request"| Spotify
    Spotify -->|"Callback with Code"| main
    main -->|"Encrypt & Store Tokens"| encrypter
    encrypter -->|"Use DB Manager"| basemanager
    basemanager -->|"Store Encrypted Data"| Firebase
    main -->|"Load & Update User"| user

    %% API Endpoints
    Client -->|"/playlist, /tracks, /player Calls"| player
    Client -->|"/playlist, /tracks, /player Calls"| playlist
    Client -->|"/playlist, /tracks, /player Calls"| tracks

    player -->|"Queue Operations"| Spotify
    playlist -->|"CRUD Playlist"| Spotify
    tracks -->|"Search Tracks"| Spotify

    player -->|"Read/Write Metadata"| Firebase
    playlist -->|"Read/Write Metadata"| Firebase
    tracks -->|"Read/Write Metadata"| Firebase

    %% UI Serving
    Browser -->|"Load UI"| main
    main -->|"Serve CSS"| style1
    main -->|"Serve CSS"| style2
    main -->|"Serve HTML"| html1
    main -->|"Serve HTML"| html2
    main -->|"Serve JS"| js

    %% Click Events
    click main "https://github.com/z4no/spotify-in-a-social-way/blob/main/main.py"
    click encrypter "https://github.com/z4no/spotify-in-a-social-way/blob/main/Encripter.py"
    click basemanager "https://github.com/z4no/spotify-in-a-social-way/blob/main/BaseManager.py"
    click user "https://github.com/z4no/spotify-in-a-social-way/blob/main/User.py"
    click player "https://github.com/z4no/spotify-in-a-social-way/blob/main/player/player_operations.py"
    click playlist "https://github.com/z4no/spotify-in-a-social-way/blob/main/playlist/playlist_operatiosn.py"
    click tracks "https://github.com/z4no/spotify-in-a-social-way/blob/main/tracks/tracks_operations.py"
    click style1 "https://github.com/z4no/spotify-in-a-social-way/blob/main/static/styles/style.css"
    click style2 "https://github.com/z4no/spotify-in-a-social-way/blob/main/static/styles/nocredentails.css"
    click html1 "https://github.com/z4no/spotify-in-a-social-way/blob/main/templates/index.html"
    click html2 "https://github.com/z4no/spotify-in-a-social-way/blob/main/templates/nocredentials.html"
    click js "https://github.com/z4no/spotify-in-a-social-way/blob/main/templates/animations.js"
    click requirements "https://github.com/z4no/spotify-in-a-social-way/blob/main/requirements.txt"
    click gitignore "https://github.com/z4no/spotify-in-a-social-way/blob/main/.gitignore"
    click readme "https://github.com/z4no/spotify-in-a-social-way/blob/main/README.md"
    click license "https://github.com/z4no/spotify-in-a-social-way/tree/main/LICENSE"
```
