# piyushk2477/music-match architecture

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

- Interactive diagram: https://gitdiagram.com/piyushk2477/music-match
- Repository: https://github.com/piyushk2477/music-match

## Overview

##### Project type and purpose
- This is a full-stack web application named “music-match.” The front end is built with React + Vite, and the back end is a Node.js/Express service. It integrates with Spotify’s APIs for authentication and data, persists user and music data in a relational database, and offers features like compare, discover, ranking, and profile pages.

##### File structure
- Top-level:
– index.html, public/ → static entry for Vite/React
– src/ → React app (components, pages, assets)
– backend/ → Node.js service (server.js, route handlers, DB scripts, migrations)
– Configuration: package.json/lock, vite.config.js, eslint.config.js, .env
- In backend/:
– server.js → Express app bootstrap
– auth.js & spotify-auth.js → OAuth flow with Spotify
– db.js & setup-database.js → Database connection and schema setup
– *.js scripts → migrations and data-fix scripts for tables/columns
– database.sql → raw schema or seed data
- In src/:
– main.jsx → React DOM entry
– App.jsx → top-level router/logic
– pages/ → page components (Home, Login, AuthCallback, Discover, Compare, Ranking, Profile)
– assets/, CSS → styling and images

##### README

a. Main Components
- Frontend: React + Vite SPA
- Backend: Node.js + Express API server
- Database: Relational (PostgreSQL/MySQL)
- External Service: Spotify Web API (OAuth + data endpoints)
- Optional: Static file host/CDN for public assets
b. Relationships & Interactions
1. User ↔ React SPA (via browser)
2. SPA ↔ Express server over HTTPS (REST or GraphQL endpoints)
3. Server ↔ Database (SQL queries through db.js)
4. Server ↔ Spotify API for OAuth and music data
5. Migration scripts ↔ Database (one-time or CI/CD migrations)
c. Architectural Patterns & Principles
– Clear separation of concerns: presentation (frontend) vs. business logic (backend) vs. persistence (DB)
– Flow-based data retrieval: UI triggers API calls, server mediates between DB and Spotify
– Modular code: separate route handlers, auth modules, migration scripts
– Environment-based config: .env in root and .env.example in backend
d. Key Technologies & Libraries
- Frontend: React, React Router, Vite, ESLint
- Backend: Node.js, Express, dotenv, any SQL client (e.g., node-pg)
- Auth: OAuth2 with Spotify (via auth.js/spotify-auth.js)
- Database: SQL (scripts in database.sql, setup-database.js, migrations)

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Client Layer"
    direction TB
    Browser["User Browser"]:::user
    subgraph "React SPA"
      direction TB
      HTML["index.html"]:::frontend
      VITE["vite.config.js"]:::frontend
      ESLINT["eslint.config.js"]:::frontend
      ENTRY["src/main.jsx"]:::frontend
      APP["src/App.jsx"]:::frontend
      CSS1["src/index.css"]:::frontend
      CSS2["src/App.css"]:::frontend
      PUBLIC["public/"]:::frontend
      subgraph "src/pages"
        direction TB
        Home["Home.jsx"]:::frontend
        Login["Login.jsx"]:::frontend
        AuthCallback["AuthCallback.jsx"]:::frontend
        Discover["Discover.jsx"]:::frontend
        Compare["Compare.jsx"]:::frontend
        Ranking["Ranking.jsx"]:::frontend
        Profile["Profile.jsx"]:::frontend
      end
      ASSETS["src/assets/"]:::frontend
    end
  end

  subgraph "API Layer"
    direction TB
    Server["backend/server.js"]:::backend
    PKG["backend/package.json\npackage-lock.json"]:::backend
    ENVEX["backend/.env.example"]:::backend
    subgraph "Auth Module"
      direction TB
      AUTH["backend/auth.js"]:::backend
      SPAUTH["backend/spotify-auth.js"]:::backend
    end
    DBCON["backend/db.js"]:::backend
    SETUP["backend/setup-database.js"]:::backend
  end

  subgraph "Persistence Layer"
    direction TB
    DB["PostgreSQL DB"]:::db
  end

  subgraph "External Services"
    direction TB
    EXTERNAL["Spotify Web API"]:::external
  end

  subgraph "Migrations & Scripts"
    direction TB
    SQL["backend/database.sql"]:::backend
    MIG1["backend/add-listening-minutes-column.js"]:::backend
    MIG2["backend/add-spotify-columns.js"]:::backend
    MIG3["backend/fix-artist-song-tables.js"]:::backend
    MIG4["backend/check-users.js"]:::backend
  end

  Browser -->|Load SPA| HTML
  Browser -->|Load SPA| ENTRY
  ENTRY -->|Render| APP
  APP -->|Load Pages| Home
  APP -->|Load Pages| Login
  APP -->|Load Pages| AuthCallback
  APP -->|Load Pages| Discover
  APP -->|Load Pages| Compare
  APP -->|Load Pages| Ranking
  APP -->|Load Pages| Profile
  APP -->|Use Assets| ASSETS
  APP -->|Uses Config| VITE
  APP -->|Uses Config| ESLINT

  Browser -->|API Requests| Server
  Server -->|Connect| DB
  Server -->|OAuth| EXTERNAL
  Server -->|Token Flow| AUTH
  Server -->|Spotify Flow| SPAUTH
  Server -->|Setup DB| SETUP

  SQL -->|Seed/Schema| DB
  MIG1 -->|Migrate| DB
  MIG2 -->|Migrate| DB
  MIG3 -->|Migrate| DB
  MIG4 -->|Check| DB

  classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
  classDef db fill:#FFA500,stroke:#333,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
  classDef user fill:#F0E68C,stroke:#333,stroke-width:1px

  click HTML "https://github.com/piyushk2477/music-match/blob/main/index.html"
  click VITE "https://github.com/piyushk2477/music-match/blob/main/vite.config.js"
  click ESLINT "https://github.com/piyushk2477/music-match/blob/main/eslint.config.js"
  click ENTRY "https://github.com/piyushk2477/music-match/blob/main/src/main.jsx"
  click APP "https://github.com/piyushk2477/music-match/blob/main/src/App.jsx"
  click CSS1 "https://github.com/piyushk2477/music-match/blob/main/src/index.css"
  click CSS2 "https://github.com/piyushk2477/music-match/blob/main/src/App.css"
  click PUBLIC "https://github.com/piyushk2477/music-match/tree/main/public/"
  click Home "https://github.com/piyushk2477/music-match/blob/main/src/pages/Home.jsx"
  click Login "https://github.com/piyushk2477/music-match/blob/main/src/pages/Login.jsx"
  click AuthCallback "https://github.com/piyushk2477/music-match/blob/main/src/pages/AuthCallback.jsx"
  click Discover "https://github.com/piyushk2477/music-match/blob/main/src/pages/Discover.jsx"
  click Compare "https://github.com/piyushk2477/music-match/blob/main/src/pages/Compare.jsx"
  click Ranking "https://github.com/piyushk2477/music-match/blob/main/src/pages/Ranking.jsx"
  click Profile "https://github.com/piyushk2477/music-match/blob/main/src/pages/Profile.jsx"
  click ASSETS "https://github.com/piyushk2477/music-match/tree/main/src/assets/"
  click Server "https://github.com/piyushk2477/music-match/blob/main/backend/server.js"
  click PKG "https://github.com/piyushk2477/music-match/blob/main/backend/package.json"
  click PKG "https://github.com/piyushk2477/music-match/blob/main/backend/package-lock.json"
  click ENVEX "https://github.com/piyushk2477/music-match/blob/main/backend/.env.example"
  click AUTH "https://github.com/piyushk2477/music-match/blob/main/backend/auth.js"
  click SPAUTH "https://github.com/piyushk2477/music-match/blob/main/backend/spotify-auth.js"
  click DBCON "https://github.com/piyushk2477/music-match/blob/main/backend/db.js"
  click SETUP "https://github.com/piyushk2477/music-match/blob/main/backend/setup-database.js"
  click SQL "https://github.com/piyushk2477/music-match/blob/main/backend/database.sql"
  click MIG1 "https://github.com/piyushk2477/music-match/blob/main/backend/add-listening-minutes-column.js"
  click MIG2 "https://github.com/piyushk2477/music-match/blob/main/backend/add-spotify-columns.js"
  click MIG3 "https://github.com/piyushk2477/music-match/blob/main/backend/fix-artist-song-tables.js"
  click MIG4 "https://github.com/piyushk2477/music-match/blob/main/backend/check-users.js"
```
