# darth-dodo/spotify-insights architecture

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

- Interactive diagram: https://gitdiagram.com/darth-dodo/spotify-insights
- Repository: https://github.com/darth-dodo/spotify-insights

## Overview

##### Project type and purpose
- This is a single-page React application (built with Vite) that serves as an analytics dashboard for Spotify users.

##### File structure
- Top-level:
- public, index.html, src/, docs/, .github/, config files (tsconfig, eslint, tailwind, vite).
- src/ splits into:
- components/ (UI components organized by feature: auth, dashboard, layout, ui primitives)
- hooks/ (React hooks for auth, theme, data, playback)
- lib/ (low-level wrappers around Spotify API, data fetchers, processors, cache, playback SDK)
- strategies/ (strategy pattern for auth and sandbox vs production data)
- pages/ (static routes: HelpPage, LegalPage, 404)
- styles/, main.tsx, App.tsx
- No backend code – all API interactions happen client-side via OAuth2 PKCE.

##### README for extra insights
- Tech stack: React 18, TypeScript, Vite, Tailwind CSS, React Query, Zustand, Shadcn/UI, Recharts, Framer Motion.
- Authentication: OAuth 2.0 PKCE against Spotify Web API.
- Data Flow: Custom data layer (lib/data) that fetches, processes, caches Spotify data, exposes to components via hooks.

a. Main components
1. User’s Browser / SPA
2. UI Layer (App, pages, components)
3. State & Data Layer
- React Query & Zustand stores
- Custom Hooks (useSpotifyData, useAuth, useToast, etc.)
4. Integration Layer (src/lib & strategies)
- Spotify-auth modules (spotify-auth-core, crypto, tokens)
- Spotify-data modules (fetcher, processor, cache, integration)
- Spotify-playback SDK & manager
- AuthStrategy & DataStrategy abstractions
5. External Services
- Spotify Authorization Server (OAuth2 endpoints)
- Spotify Web API (data endpoints)
6. Optional Local Storage / In-memory cache

b. Relationships and interactions
- UI components dispatch actions or call hooks → hooks consult React Query / Zustand → query functions in lib/data → call Spotify-data-fetcher → hit Spotify Web API → process & cache data → return to UI.
- Auth flow: UI triggers AuthProvider → strategy picks production or sandbox → PKCE handshake with Spotify Auth Server → receive tokens → store in cache → tokens used by data fetch calls.
- Playback flow: UI playback controls → hooks call spotify-playback-manager → playback-SDK injects script → events flow back to manager → UI updates.

c. Architectural patterns and principles
- Component-based UI (Shadcn/UI, custom layout & dashboard widgets)
- Provider pattern for cross-cutting concerns (AuthProvider, ThemeProvider, LoadingProvider)
- Strategy pattern for swapping auth/data implementations (sandbox vs production)
- Separation of concerns between UI, hooks, integration, and external communication
- Caching & data normalization in lib layer to optimize API usage

d. Key technologies / libraries
- React 18 + TypeScript + Vite
- React Query (async data) + Zustand (client state)
- Tailwind CSS + Shadcn/UI (styling & components)
- Recharts for charts, Framer Motion for animations
- OAuth2 PKCE modules in src/lib/auth
- Spotify-playback SDK in src/lib/playback

- Use clear labels: “Browser SPA,” “AuthProvider,” “Spotify Data Fetcher,” “Spotify Web API,” etc.
- UI → Hooks → Data Layer → External API
- UI → AuthProvider → Auth Server → Tokens → Data Layer
- Playback controls → Playback SDK → Browser Audio context
- “UI Layer,” “State & Hooks,” “Integration Layer,” “External Services.”

## Diagram (Mermaid)

```mermaid
graph TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        SPAEntry["SPA Entry<br/>index.html, src/main.tsx"]:::ui
        App["App.tsx"]:::ui
        subgraph "Pages"
            direction TB
            IndexPage["Index.tsx"]:::ui
            HelpPage["HelpPage.tsx"]:::ui
            LegalPage["LegalPage.tsx"]:::ui
            NotFoundPage["NotFound.tsx"]:::ui
        end
        subgraph "Auth Components"
            direction TB
            AuthDialog["AuthDialog.tsx"]:::ui
            AuthGuard["AuthGuard.tsx"]:::ui
            CallbackPage["CallbackPage.tsx"]:::ui
            ErrorDialog["ErrorDialog.tsx"]:::ui
            LoginPage["LoginPage.tsx"]:::ui
        end
        subgraph "Dashboard Components"
            direction TB
            DashboardOverview["DashboardOverview.tsx"]:::ui
            GenreAnalysis["GenreAnalysis.tsx"]:::ui
            ListeningTrends["ListeningTrends.tsx"]:::ui
        end
        subgraph "Layout Components"
            direction TB
            Header["Header.tsx"]:::ui
            Footer["Footer.tsx"]:::ui
            Sidebar["Sidebar.tsx"]:::ui
        end
        subgraph "UI Primitives"
            direction TB
            UIPackage["src/components/ui"]:::ui
        end
        subgraph "Providers"
            direction TB
            ProvidersPkg["src/components/providers"]:::ui
        end
    end

    %% State & Hooks
    subgraph "State & Hooks"
        direction TB
        HooksPkg["src/hooks"]:::state
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        subgraph "Auth Integration"
            direction TB
            AuthLib["src/lib/auth"]:::lib
        end
        subgraph "Data Integration"
            direction TB
            DataLib["src/lib/data"]:::lib
        end
        subgraph "Core Utilities"
            direction TB
            CoreLib["src/lib"]:::lib
        end
        subgraph "Playback Integration"
            direction TB
            PlaybackLib["src/lib/playback"]:::lib
        end
        subgraph "Strategy Implementations"
            direction TB
            Strategies["src/strategies"]:::lib
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SpotifyAuth["Spotify Authorization Server"]:::ext
        SpotifyAPI["Spotify Web API"]:::ext
        BrowserAudio["Browser Audio Context"]:::ext
    end

    %% Connections
    SPAEntry --> App
    App --> Pages
    App --> AuthComponents
    App --> DashboardComponents
    App --> LayoutComponents
    App --> UIPackage
    App --> ProvidersPkg

    AuthComponents --> HooksPkg
    DashboardComponents --> HooksPkg
    LayoutComponents --> HooksPkg
    UIPackage --> HooksPkg
    ProvidersPkg --> HooksPkg

    HooksPkg --> AuthLib
    HooksPkg --> DataLib
    HooksPkg --> PlaybackLib

    AuthLib --> SpotifyAuth
    SpotifyAuth --> AuthLib

    AuthLib --> DataLib
    DataLib --> SpotifyAPI
    SpotifyAPI --> DataLib

    PlaybackLib --> BrowserAudio
    BrowserAudio --> PlaybackLib

    DataLib --> HooksPkg
    HooksPkg --> App

    %% Click Events
    click SPAEntry "https://github.com/darth-dodo/spotify-insights/blob/main/index.html"
    click SPAEntry "https://github.com/darth-dodo/spotify-insights/blob/main/src/main.tsx"
    click App "https://github.com/darth-dodo/spotify-insights/blob/main/src/App.tsx"
    click IndexPage "https://github.com/darth-dodo/spotify-insights/blob/main/src/pages/Index.tsx"
    click HelpPage "https://github.com/darth-dodo/spotify-insights/blob/main/src/pages/HelpPage.tsx"
    click LegalPage "https://github.com/darth-dodo/spotify-insights/blob/main/src/pages/LegalPage.tsx"
    click NotFoundPage "https://github.com/darth-dodo/spotify-insights/blob/main/src/pages/NotFound.tsx"
    click AuthDialog "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/auth/AuthDialog.tsx"
    click AuthGuard "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/auth/AuthGuard.tsx"
    click CallbackPage "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/auth/CallbackPage.tsx"
    click ErrorDialog "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/auth/ErrorDialog.tsx"
    click LoginPage "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/auth/LoginPage.tsx"
    click DashboardOverview "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/dashboard/DashboardOverview.tsx"
    click GenreAnalysis "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/dashboard/GenreAnalysis.tsx"
    click ListeningTrends "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/dashboard/ListeningTrends.tsx"
    click Header "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/layout/Header.tsx"
    click Footer "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/layout/Footer.tsx"
    click Sidebar "https://github.com/darth-dodo/spotify-insights/blob/main/src/components/layout/Sidebar.tsx"
    click UIPackage "https://github.com/darth-dodo/spotify-insights/tree/main/src/components/ui"
    click ProvidersPkg "https://github.com/darth-dodo/spotify-insights/tree/main/src/components/providers"
    click HooksPkg "https://github.com/darth-dodo/spotify-insights/tree/main/src/hooks"
    click AuthLib "https://github.com/darth-dodo/spotify-insights/tree/main/src/lib/auth"
    click DataLib "https://github.com/darth-dodo/spotify-insights/tree/main/src/lib/data"
    click CoreLib "https://github.com/darth-dodo/spotify-insights/tree/main/src/lib"
    click PlaybackLib "https://github.com/darth-dodo/spotify-insights/tree/main/src/lib/playback"
    click Strategies "https://github.com/darth-dodo/spotify-insights/tree/main/src/strategies"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6;
    classDef state fill:#DFFFE0,stroke:#2E8B57;
    classDef lib fill:#FFE5B4,stroke:#CD8500;
    classDef ext fill:#E5E0FF,stroke:#6A5ACD;
```
