# droopytersen/better-spotify architecture

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

- Interactive diagram: https://gitdiagram.com/droopytersen/better-spotify
- Repository: https://github.com/droopytersen/better-spotify

## Overview

##### Main Components

a) Client Layer:
- React Frontend (based on the /app directory structure)
- UI Components (shadcn components)
- Client-side Services
- Playlist Builder Interface

b) Server Layer:
- Authentication System
- Spotify Integration Services
- Database Layer
- Playlist Generation Engine
- Sync Services

c) External Services:
- Spotify API
- LLM Service (mentioned in README)

##### Key Architectural Elements

**1. Frontend Architecture:**
- ┌─────────────────────────────────────────┐
- Client Layer                            │
- ┌─────────────┐ ┌────────────────────┐ │
- UI Components│ │ Client-side Services│ │
- (Shadcn)    │ │ - Playlist Builder  │ │
- Buttons   │ │ - Spotify SDK      │ │
- Cards     │ │ - Data Sync        │ │
- ┘ └────────────────────┘ │
- ┘

**2. Server Architecture:**
- ┌─────────────────────────────────────────┐
- Server Layer                            │
- ┌─────────────┐ ┌────────────────────┐ │
- Auth System │ │ Playlist Generator  │ │
- (Spotify)   │ │ - Song Pool Builder│ │
- LLM Integration  │ │
- ┘ └────────────────────┘ │
- ┌─────────────┐ ┌────────────────────┐ │
- Data Sync   │ │ Database Layer     │ │
- Services    │ │ (PGLite)           │ │
- ┘ └────────────────────┘ │
- ┘

##### Important Flows to Highlight

a) Authentication Flow:
- User → Auth System → Spotify OAuth → Token Storage

b) Playlist Generation Flow:
- User Input → Playlist Builder → Song Pool Generation → LLM Curation → Spotify API

c) Data Sync Flow:
- Spotify API → Sync Services → Database → Client Cache

**┌─────────────┐    ┌──────────────┐    ┌────────────┐**
- Input Parser│ → │Song Pool Gen.│ → │LLM Curation│
- ┘    └──────────────┘    └────────────┘

##### Key Relationships

- Frontend to Backend communication via API routes
- Database interactions with sync services
- External service integration points
- Cache and state management flow

##### Technical Stack Indicators

- React (Frontend framework)
- TypeScript (Language)
- PGLite (Database)
- Spotify SDK
- Shadcn (UI Components)

##### Additional Elements

- Version/environment indicators
- Scaling points and potential bottlenecks
- Error handling paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        UI["UI Components"]
        ClientServices["Client Services"]
        PlaylistUI["Playlist Builder UI"]
        Layout["Layout System"]
    end

    subgraph Server
        Auth["Authentication System"]
        PlaylistGen["Playlist Generation Engine"]
        SyncService["Sync Services"]
        DB[(Database Layer)]
    end

    subgraph External
        SpotifyAPI["Spotify API"]
        LLM["LLM Service"]
    end

    %% Client Layer Relationships
    UI --> ClientServices
    ClientServices --> PlaylistUI
    UI --> Layout

    %% Server Layer Relationships
    Auth --> DB
    PlaylistGen --> DB
    SyncService --> DB

    %% External Integration
    ClientServices <--> SpotifyAPI
    PlaylistGen <--> LLM
    SyncService <--> SpotifyAPI
    Auth <--> SpotifyAPI

    %% Cross-Layer Communication
    ClientServices <--> Auth
    PlaylistUI <--> PlaylistGen
    ClientServices <--> SyncService

    %% Styling
    classDef client fill:#a8d1ff,stroke:#333,stroke-width:2px
    classDef server fill:#90EE90,stroke:#333,stroke-width:2px
    classDef external fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef database fill:#f9f,stroke:#333,stroke-width:2px

    class UI,ClientServices,PlaylistUI,Layout client
    class Auth,PlaylistGen,SyncService server
    class SpotifyAPI,LLM external
    class DB database

    %% Click Events
    click UI "https://github.com/DroopyTersen/better-spotify/tree/main/app/shadcn/components/ui"
    click Auth "https://github.com/DroopyTersen/better-spotify/tree/main/app/auth"
    click PlaylistGen "https://github.com/DroopyTersen/better-spotify/tree/main/app/spotify/playlistBuilder"
    click DB "https://github.com/DroopyTersen/better-spotify/tree/main/app/db"
    click SyncService "https://github.com/DroopyTersen/better-spotify/tree/main/app/spotify/sync"
    click ClientServices "https://github.com/DroopyTersen/better-spotify/tree/main/app/spotify"
    click Layout "https://github.com/DroopyTersen/better-spotify/tree/main/app/layout"
    click PlaylistUI "https://github.com/DroopyTersen/better-spotify/blob/main/app/spotify/playlistBuilder/BuilderForm.tsx"

    %% Legend
    subgraph Legend
        Client_L["Client Component"]:::client
        Server_L["Server Component"]:::server
        External_L["External Service"]:::external
        DB_L[(Database)]:::database
    end
```
