# harsheeee/spotify-stats architecture

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

- Interactive diagram: https://gitdiagram.com/harsheeee/spotify-stats
- Repository: https://github.com/harsheeee/spotify-stats

## Overview

##### Project Type and Purpose
- This is a full-stack web application:
- Frontend: React + TypeScript + Vite + Tailwind CSS
- Backend: Go HTTP server performing OAuth with Spotify and proxying API calls
- No on-prem database layer—data is fetched live from the Spotify Web API

##### File Structure
- Top-level:
- backend/ – Go service entrypoint (main.go), handlers/, models/
- frontend/ – Vite + React SPA (src/, public/, config files)
- Patterns:
- SPA communicates over REST endpoints exposed by Go backend
- OAuth dance handled in backend handlers
- Utility functions in frontend/src/lib/utils.ts

##### Main Components
A. User’s Web Browser (SPA)
B. Frontend Application
- UI components (Dashboard, HomePage, UI library)
- Client-side router & state
C. Backend API Service
- HTTP server (main.go)
- OAuth & token handling (models/tokenResponse.go)
- Request handlers (handlers/handlers.go)
D. External Service
- Spotify Accounts Service (OAuth endpoints)
- Spotify Web API (data endpoints)

##### Component Relationships & Data Flows
1) User → Browser SPA
- Initiates “Sign in with Spotify”
2) SPA → Backend (/login, /callback)
- Backend redirects to Spotify Accounts Service
3) Spotify Accounts → Backend
- Callback with authorization code → Backend exchanges for access token
4) Browser SPA ← Backend (tokenResponse)
- Backend returns token (or session cookie) to SPA
5) SPA → Backend (/top-artists, /top-tracks)
- Backend uses access token to call Spotify Web API
6) Backend → Spotify Web API
- Fetch user data (top artists/tracks)
7) Browser SPA ← Backend
- Receives JSON payload, renders charts

##### Architectural Patterns & Design Principles
- Single-page app (SPA) with a thin API backend
- Clear separation of concerns: UI vs. business logic vs. external API integration
- RESTful API endpoints in Go
- OAuth 2.0 Authorization Code Grant flow
- No persistent storage—stateless backend

##### Technologies & Frameworks to Call Out
- Frontend: React, TypeScript, Vite, Tailwind CSS
- Backend: Go (net/http), Go modules (go.mod), custom handlers
- External: Spotify OAuth + Web API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Web Browser Layer
    Browser["Web Browser / SPA"]:::frontend
    click Browser "https://github.com/harsheeee/spotify-stats/blob/main/frontend/index.html"

    %% Frontend Layer
    subgraph "Frontend Application" 
        direction TB
        AppApp["App.tsx (App Shell)"]:::frontend
        click AppApp "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/App.tsx"
        AppMain["main.tsx (Bootstrapping)"]:::frontend
        click AppMain "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/main.tsx"
        Dashboard["Dashboard Page"]:::frontend
        click Dashboard "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/components/Dashboard.tsx"
        HomePage["Home Page"]:::frontend
        click HomePage "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/components/HomePage.tsx"
        subgraph "UI Library Components"
            direction TB
            Avatar["Avatar"]:::frontend
            click Avatar "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/components/ui/avatar.tsx"
            Button["Button"]:::frontend
            click Button "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/components/ui/button.tsx"
            Card["Card"]:::frontend
            click Card "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/components/ui/card.tsx"
            Input["Input"]:::frontend
            click Input "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/components/ui/input.tsx"
            Label["Label"]:::frontend
            click Label "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/components/ui/label.tsx"
        end
        Utils["Utility Functions"]:::frontend
        click Utils "https://github.com/harsheeee/spotify-stats/blob/main/frontend/src/lib/utils.ts"
        subgraph "Config & Assets"
            direction TB
            Static["Static files"]:::frontend
            click Static "https://github.com/harsheeee/spotify-stats/tree/main/frontend/public/"
            ViteCfg["vite.config.ts"]:::frontend
            click ViteCfg "https://github.com/harsheeee/spotify-stats/blob/main/frontend/vite.config.ts"
            TailwindCfg["tailwind.config.ts"]:::frontend
            click TailwindCfg "https://github.com/harsheeee/spotify-stats/blob/main/frontend/tailwind.config.ts"
            Ts1["tsconfig.json"]:::frontend
            click Ts1 "https://github.com/harsheeee/spotify-stats/blob/main/frontend/tsconfig.json"
            Ts2["tsconfig.app.json"]:::frontend
            click Ts2 "https://github.com/harsheeee/spotify-stats/blob/main/frontend/tsconfig.app.json"
        end
    end

    %% Backend Layer
    subgraph "Backend API Service" 
        direction TB
        Service["Go HTTP Server"]:::backend
        click Service "https://github.com/harsheeee/spotify-stats/blob/main/backend/main.go"
        Handlers["Request Handlers"]:::backend
        click Handlers "https://github.com/harsheeee/spotify-stats/blob/main/backend/handlers/handlers.go"
        TokenModel["OAuth Token Models"]:::backend
        click TokenModel "https://github.com/harsheeee/spotify-stats/blob/main/backend/models/tokenResponse.go"
        GoMod["Go Module Config"]:::backend
        click GoMod "https://github.com/harsheeee/spotify-stats/blob/main/backend/go.mod"
        click GoMod "https://github.com/harsheeee/spotify-stats/blob/main/backend/go.sum"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Accounts["Spotify Accounts Service"]:::external
        WebAPI["Spotify Web API"]:::external
    end

    %% Connections with sequence labels
    Browser -->|"(1) load SPA"| AppApp
    AppMain -->|"(2) POST /login"| Service
    Service -->|"(3) redirect to OAuth"| Accounts
    Accounts -->|"(4) OAuth callback"| Handlers
    Handlers -->|"exchange code"| TokenModel
    TokenModel -->|"return token"| Browser
    Browser -->|"(5) GET /top-artists"| Service
    Service -->|"calls Web API"| WebAPI
    WebAPI -->|"user data JSON"| Service
    Service -->|"return JSON"| Dashboard

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
