# shivam0912/spotify-but-better architecture

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

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

## Overview

##### Main Components
- Frontend Application:
- Built with React, TailwindCSS, ShadCN components, and Zustand for state management.
- Contains pages for home, album details, authentication flows, admin panels, chat screens, etc.
- Integrates with backend REST API endpoints via Axios (or similar utility) and connects to Socket.io for real-time chat.
- Backend Application:
- Node.js and Express server handling REST API requests.
- Controllers, routes, models (for users, albums, songs, messages, etc.) implementing the MVC pattern.
- Middlewares (like authentication) to protect routes.
- Integration with external services:
- Cloudinary for media storage (songs and album covers).
- Socket.io for real-time chat messaging.
- Mongoose connection to a MongoDB database.
- Seed scripts for initializing core data (albums and songs).
- External Services:
- MongoDB as the primary database.
- Cloudinary for cloud storage.
- Clerk for authentication (facilitating user sessions and profile management).
- Real-time Communication:
- Socket.io implemented in both backend (server) and frontend (client) for live chat functionality.

##### Relationships and Interactions
- The Frontend interacts with the Backend via:
- HTTP REST API calls for data (music streaming data, user profiles, album info, etc.).
- A persistent Socket.io connection for real-time communication (chat).
- The Backend handles these requests by:
- Routing API calls to specific controllers (e.g., auth, admin, album, song, stats, users controllers).
- Applying middlewares for authentication and data validation.
- Communicating with the database (using Mongoose models) for CRUD operations.
- Leveraging the Cloudinary service (via dedicated lib/cloudinary.js) to manage media uploads and retrieval.
- The database (MongoDB) and Cloudinary serve as essential resources for storing application data and media files respectively.

##### Architectural Patterns and Design Principles
- MVC Pattern on the Backend:
- Controllers (located in backend/src/controllers) interact with Models and serve data via routes.
- Separation of Concerns:
- Clear distinction between frontend (presentation layer) and backend (API and business logic).
- Real-time Communication:
- Dedicated integration of Socket.io ensuring efficient, bidirectional messaging.
- Third-Party Service Integration:
- Use of external authentication services (Clerk) and media storage (Cloudinary) integrated within the backend logic.

##### Incorporate Relevant Technologies
- Frontend: React, TailwindCSS, ShadCN, Zustand, and Socket.io-client.
- Backend: Node.js, Express, Socket.io, Mongoose (for MongoDB), and Cloudinary.
- Additional tools: ESLint (for code quality), Vite (for frontend bundling), and various configuration files (package.json, tsconfig, etc.) to manage the build and dependencies.

##### Instructing the Principal Software Engineer
- Frontend Block: Representing components, UI pages (admin, album, chat, auth, home), state management with Zustand, and integration points (Axios and Socket.io-client).
- Backend Block: Detailing the Express server, divided into Controllers, Routes, Models, Middlewares, and Lib modules that integrate with Cloudinary and the database.
- Visual Distinctions:
- Remember to capture any scheduled tasks (like if Node-cron is implemented for background jobs) as auxiliary processes if relevant.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend"
        FE["Frontend Application"]:::frontend
        F1["Home Page"]:::frontend
        F2["Album Page"]:::frontend
        F3["Auth Page"]:::frontend
        F4["Admin Page"]:::frontend
        F5["Chat Page"]:::frontend
        F6["State Management (Zustand)"]:::frontend
        F7["HTTP Integration (Axios)"]:::frontend
        F8["Socket.io Client"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        BE["Backend Application"]:::backend
        B1["API Routes"]:::backend
        B2["API Controllers"]:::backend
        B3["Models"]:::backend
        B4["Middlewares"]:::backend
        B5["Cloudinary Integration"]:::backend
        B6["Socket.io Integration"]:::backend
        B7["Database Connection"]:::backend
        B8["Seed Scripts"]:::backend
    end

    %% External Services Layer
    subgraph "External Services"
        E1["MongoDB"]:::external
        E2["Cloudinary Service"]:::external
        E3["Clerk Service"]:::external
    end

    %% Frontend to Backend Communication
    F7 -->|"REST_API"| B1
    F8 -->|"Socket.io"| B6

    %% Backend internal communications
    B1 -->|"routes_to"| B2
    B2 -->|"controllers_to"| B3
    B2 -->|"auth"| B4
    B2 -->|"media"| B5
    B2 -->|"realtime"| B6
    B2 -->|"data"| B7
    B8 -->|"init"| B7
    B7 -->|"connects"| E1
    B5 -->|"uploads"| E2
    B4 -->|"validate"| E3

    %% Frontend individual pages and modules linking to main Frontend Application
    FE --> F1
    FE --> F2
    FE --> F3
    FE --> F4
    FE --> F5
    FE --> F6
    FE --> F7
    FE --> F8

    %% Frontend authentication integration with Clerk
    F3 -->|"auth_call"| E3

    %% Backend main application wrapping routes
    BE --> B1
    BE --> B2
    BE --> B3
    BE --> B4
    BE --> B5
    BE --> B6
    BE --> B7
    BE --> B8

    %% Click Events for Frontend Components
    click FE "https://github.com/shivam0912/spotify-but-better/tree/master/frontend/" "Frontend Application Directory"
    click F1 "https://github.com/shivam0912/spotify-but-better/blob/master/frontend/src/pages/home/HomePage.tsx" "Home Page File"
    click F2 "https://github.com/shivam0912/spotify-but-better/blob/master/frontend/src/pages/album/AlbumPage.tsx" "Album Page File"
    click F3 "https://github.com/shivam0912/spotify-but-better/blob/master/frontend/src/pages/auth/AuthCallbackPage.tsx" "Auth Page File"
    click F4 "https://github.com/shivam0912/spotify-but-better/blob/master/frontend/src/pages/admin/AdminPage.tsx" "Admin Page File"
    click F4 "https://github.com/shivam0912/spotify-but-better/tree/master/frontend/src/pages/admin/" "Admin Components Directory"
    click F5 "https://github.com/shivam0912/spotify-but-better/blob/master/frontend/src/pages/chat/ChatPage.tsx" "Chat Page File"
    click F6 "https://github.com/shivam0912/spotify-but-better/tree/master/frontend/src/stores/" "Zustand Stores Directory"
    click F7 "https://github.com/shivam0912/spotify-but-better/blob/master/frontend/src/lib/axios.ts" "HTTP Integration File"

    %% Click Events for Backend Components
    click BE "https://github.com/shivam0912/spotify-but-better/tree/master/backend/" "Backend Application Directory"
    click B2 "https://github.com/shivam0912/spotify-but-better/tree/master/backend/src/controllers/" "API Controllers Directory"
    click B1 "https://github.com/shivam0912/spotify-but-better/tree/master/backend/src/routes/" "API Routes Directory"
    click B3 "https://github.com/shivam0912/spotify-but-better/tree/master/backend/src/models/" "Models Directory"
    click B4 "https://github.com/shivam0912/spotify-but-better/blob/master/backend/src/middlewares/auth.middleware.js" "Authentication Middleware File"
    click B5 "https://github.com/shivam0912/spotify-but-better/blob/master/backend/src/lib/cloudinary.js" "Cloudinary Integration File"
    click B6 "https://github.com/shivam0912/spotify-but-better/blob/master/backend/src/lib/socket.js" "Socket.io Integration File"
    click B7 "https://github.com/shivam0912/spotify-but-better/blob/master/backend/src/lib/db.js" "Database Connection File"
    click B8 "https://github.com/shivam0912/spotify-but-better/tree/master/backend/src/seeds/" "Seed Scripts Directory"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef external fill:#ffcdd2,stroke:#c62828,stroke-width:2px;
```
