# feli05/spotifytracker architecture

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

- Interactive diagram: https://gitdiagram.com/feli05/spotifytracker
- Repository: https://github.com/feli05/spotifytracker

## Overview

##### Project type and purpose
- This is a full-stack, containerized web application called **Spotify-Tracker**.
- Frontend and backend logic are implemented as a Next.js app (React + serverless API routes).
- A separate Python/Flask “ml-service” container performs model training and inference for music recommendations.
- Data stores include MongoDB Atlas (song metadata, user preferences, recommendations) and Supabase PostgreSQL (Spotify OAuth tokens and user auth).

##### Main components
a. **User Interface (Next.js App)**
- Renders pages (login/register, dashboard, recommendation flows) in the browser.
- Hosted in the “web” Docker container.
b. **Next.js Serverless API**
- Routes under `/src/app/api/*`.
- Handles:
- Auth endpoints (login, logout) via Supabase.
- Spotify OAuth flows and profile/data fetch.
- MongoDB CRUD (songs, preferences, questionnaires, recommendations).
- Proxy to ML service: `/api/ml/process-data`.
- External preview-finder calls.
c. **ML Service (Flask App)**
- Separate Docker container “ml-service.”
- Exposes REST endpoints for clustering, feature extraction, scoring, recommendation.
d. **Databases**
- **Supabase/PostgreSQL**: stores OAuth tokens (`spotify_tokens`), user accounts.
- **MongoDB Atlas**: stores collections: songs, user preferences, questionnaires, generated recommendations.
e. **External Services**
- **Spotify API**: user data, top tracks/artists, playback preview.
- **Supabase Auth**: sign-up/login, row-level security.
f. **Import Scripts**
- One-off Node scripts under `src/import-scripts` that fetch and seed song data into MongoDB.

##### Relationships and interactions (data flows)
- Browser → Next.js serverless API → Supabase Auth (login/signup).
- Browser → Next.js → Spotify OAuth → Supabase PostgreSQL (store tokens).
- Browser → Next.js → MongoDB (fetch songs, preferences, recs).
- Next.js API → ML service → MongoDB (upon `/api/ml/process-data` requests).
- Import scripts (CLI, Node) → Spotify Web API & MongoDB (initial seed).

##### Architectural patterns and design principles
- **Separation of Concerns**:
- Presentation layer (React pages, components)
- Business logic (API routes)
- Data layer (MongoDB, PostgreSQL)
- ML layer (Flask service)
- **Micro-service boundary**: isolates compute-heavy ML workloads.
- **Serverless functions**: Next.js API routes auto-scale.
- **Containerization**: Docker Compose for environment consistency.

##### Technologies, frameworks, libraries
- **Next.js (App Router)**, **TypeScript**, **Tailwind CSS**, **HeroUI**, **Framer Motion**
- **Flask**, **scikit-learn**, **pandas**
- **MongoDB Atlas**, **Supabase (Postgres + Auth)**
- **Docker**, **Docker Compose**
- **spotify-preview-finder** utility

- Component boundaries clearly drawn.
- Docker Compose orchestration indicated (web ⇄ ml-service).
- Environment variables/config layers (e.g., `.env`) can be noted but are optional.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Web App (Next.js + React)" 
        direction TB
        UI["Browser (React UI)"]:::frontend
        API["Next.js Serverless API"]:::api
    end

    %% ML Service Layer
    subgraph "ML Service (Flask)" 
        direction TB
        MLApp["Flask App"]:::ml
        Clustering["Clustering"]:::ml
        Feature["Feature Extraction"]:::ml
        Scoring["Scoring"]:::ml
        Recommendation["Recommendation"]:::ml
        MLApp --> Clustering
        MLApp --> Feature
        MLApp --> Scoring
        MLApp --> Recommendation
    end

    %% Data Layer
    subgraph "Data Stores"
        direction TB
        SupaDB["Supabase (PostgreSQL)"]:::db
        MongoDB["MongoDB Atlas"]:::db
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        SpotifyAPI["Spotify API"]:::external
        SupaAuth["Supabase Auth"]:::external
    end

    %% Import Scripts
    Import["Import Scripts (Node CLI)"]:::import

    %% Docker Compose
    Docker["Docker Compose"]:::config

    %% Connections
    UI -->|"REST/JSON"| API
    API -->|"OAuth2 Token Exchange"| SupaAuth
    API -->|"CRUD operations"| MongoDB
    API -->|"REST/JSON"| MLApp
    API -->|"Spotify OAuth & Data"| SpotifyAPI
    MLApp -->|"Read/Write"| MongoDB
    Import -->|"Seed Data via API"| SpotifyAPI
    Import -->|"Seed Data"| MongoDB
    Docker -->|"orchestrates"| UI
    Docker -->|"orchestrates"| MLApp

    %% Click Events
    click UI "https://github.com/feli05/spotifytracker/tree/main/src/app"
    click API "https://github.com/feli05/spotifytracker/tree/main/src/app/api"
    click MLApp "https://github.com/feli05/spotifytracker/tree/main/ml-service"
    click Import "https://github.com/feli05/spotifytracker/tree/main/src/import-scripts"
    click SupaDB "https://github.com/feli05/spotifytracker/blob/main/src/lib/supabase.ts"
    click MongoDB "https://github.com/feli05/spotifytracker/blob/main/src/lib/mongodb.ts"
    click SpotifyAPI "https://github.com/feli05/spotifytracker/blob/main/src/lib/spotify.ts"
    click SpotifyPreview "https://github.com/feli05/spotifytracker/blob/main/src/app/api/spotify-preview/route.ts"
    click Docker "https://github.com/feli05/spotifytracker/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef api fill:#D6F5D6,stroke:#28a745,color:#155724
    classDef ml fill:#FFE5B4,stroke:#ff8c00,color:#8B4513
    classDef db fill:#E0D6F5,stroke:#6f42c1,color:#4B0082
    classDef external fill:#F0F0F0,stroke:#6c757d,color:#343a40
    classDef import fill:#FFF3CD,stroke:#ffc107,color:#856404
    classDef config fill:#F5F5F5,stroke:#17a2b8,color:#0c5460
```
