# moses-tec/spotify-clone architecture

> Architecture diagram of the GitHub repository moses-tec/spotify-clone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moses-tec/spotify-clone
- Repository: https://github.com/moses-tec/spotify-clone

## Overview

This is a Spotify-style music streaming application with album and song browsing, playback, chat, authentication, and an admin catalog. Users enter through the routed frontend; authenticated sessions initialize API credentials and chat connectivity, while the backend exposes catalog, user, admin, and statistics routes. Admins can upload songs and albums, and backend controllers persist catalog data and retrieve statistics. The source index supports the cited module relationships; frontend-to-API calls and some unsampled feature internals are not shown, so those links are omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/App.tsx) (App routes), [`backend/src/index.js`](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/index.js) (HTTP server), [`backend/src/controller/admin.controller.js`](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/admin.controller.js) (Catalog management), [`backend/src/models/song.model.js`](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/song.model.js) (Song records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["App routes<br/>[App.tsx]"]
  node_home["Home discovery<br/>[HomePage.tsx]"]
  node_album_view["Album view<br/>[AlbumPage.tsx]"]
  node_player["Playback controls"]
  node_layout["Main layout<br/>[MainLayout.tsx]"]
end

subgraph group_identity["Identity and chat"]
  node_chat_view["Chat page<br/>[ChatPage.tsx]"]
  node_chat_users["Chat user list<br/>[UsersList.tsx]"]
  node_auth_provider["Auth provider<br/>[AuthProvider.tsx]"]
  node_auth_store["Auth state<br/>[useAuthStore.ts]"]
  node_chat_store["Chat state<br/>[useChatStore.ts]"]
  node_user_controller["User and messages<br/>[user.controller.js]"]
  node_socket_service["Realtime socket<br/>[socket.js]"]
end

subgraph group_catalog["Catalog and administration"]
  node_admin_ui["Admin console<br/>[AdminPage.tsx]"]
  node_song_controller["Song queries<br/>[song.controller.js]"]
  node_album_controller["Album queries"]
  node_admin_controller["Catalog management"]
  node_stats_controller["Catalog statistics<br/>[stat.controller.js]"]
end

subgraph group_server["Backend runtime and data"]
  node_http_entry["HTTP server<br/>[index.js]"]
  node_song_routes["Song routes<br/>[song.route.js]"]
  node_album_routes["Album routes<br/>[album.route.js]"]
  node_admin_routes["Admin routes<br/>[admin.route.js]"]
  node_song_model[("Song records<br/>[song.model.js]")]
  node_album_model[("Album records<br/>[album.model.js]")]
  node_user_model[("User records<br/>[user.model.js]")]
  node_message_model[("Message records<br/>[message.model.js]")]
end

node_listener(("Listener"))
node_cloudinary{{"Cloudinary"}}
node_clerk{{"Clerk identity"}}
node_database[("MongoDB")]

node_listener -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_album_view
node_app -->|"routes to"| node_chat_view
node_app -->|"routes to"| node_admin_ui
node_app -->|"wraps"| node_layout
node_layout -->|"renders"| node_player
node_chat_view -->|"renders"| node_chat_users
node_auth_provider -->|"checks admin"| node_auth_store
node_auth_provider -->|"starts socket"| node_chat_store
node_auth_provider -->|"gets token"| node_clerk
node_http_entry -->|"mounts routes"| node_song_routes
node_http_entry -->|"mounts routes"| node_album_routes
node_http_entry -->|"mounts routes"| node_admin_routes
node_song_routes -->|"dispatches"| node_song_controller
node_album_routes -->|"dispatches"| node_album_controller
node_admin_routes -->|"dispatches"| node_admin_controller
node_song_controller -->|"queries"| node_song_model
node_album_controller -->|"queries"| node_album_model
node_admin_controller -->|"writes"| node_song_model
node_admin_controller -->|"writes"| node_album_model
node_admin_controller -->|"uploads media"| node_cloudinary
node_stats_controller -->|"counts and aggregates"| node_song_model
node_stats_controller -->|"counts and aggregates"| node_album_model
node_stats_controller -->|"counts"| node_user_model
node_user_controller -->|"queries"| node_user_model
node_user_controller -->|"queries"| node_message_model
node_http_entry -->|"initializes"| node_socket_service
node_socket_service -->|"uses"| node_message_model
node_http_entry -->|"connects"| node_database
node_song_model -.->|"stores records"| node_database
node_album_model -.->|"stores records"| node_database
node_user_model -.->|"stores records"| node_database
node_message_model -.->|"stores records"| node_database

click node_app "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/home/HomePage.tsx"
click node_album_view "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/album/AlbumPage.tsx"
click node_player "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/layout/components/PlaybackControls.tsx"
click node_layout "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/layout/MainLayout.tsx"
click node_admin_ui "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/admin/AdminPage.tsx"
click node_chat_view "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/chat/ChatPage.tsx"
click node_chat_users "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/chat/components/UsersList.tsx"
click node_auth_provider "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/providers/AuthProvider.tsx"
click node_auth_store "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/stores/useAuthStore.ts"
click node_chat_store "https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/stores/useChatStore.ts"
click node_http_entry "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/index.js"
click node_song_routes "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/routes/song.route.js"
click node_song_controller "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/song.controller.js"
click node_album_routes "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/routes/album.route.js"
click node_album_controller "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/album.controller.js"
click node_admin_routes "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/routes/admin.route.js"
click node_admin_controller "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/admin.controller.js"
click node_stats_controller "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/stat.controller.js"
click node_user_controller "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/user.controller.js"
click node_socket_service "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/lib/socket.js"
click node_song_model "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/song.model.js"
click node_album_model "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/album.model.js"
click node_user_model "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/user.model.js"
click node_message_model "https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/message.model.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_home,node_album_view,node_player,node_layout toneBlue
class node_chat_view,node_chat_users,node_auth_provider,node_auth_store,node_chat_store,node_user_controller,node_socket_service,node_database toneAmber
class node_admin_ui,node_song_controller,node_album_controller,node_admin_controller,node_stats_controller toneMint
class node_http_entry,node_song_routes,node_album_routes,node_admin_routes,node_song_model,node_album_model,node_user_model,node_message_model toneRose
class node_listener,node_cloudinary,node_clerk toneIndigo
```

## Components

### Client experience

- [App routes](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Home discovery](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/home/HomePage.tsx): `frontend/src/pages/home/HomePage.tsx`
- [Album view](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/album/AlbumPage.tsx): `frontend/src/pages/album/AlbumPage.tsx`
- [Playback controls](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/layout/components/PlaybackControls.tsx): `frontend/src/layout/components/PlaybackControls.tsx`
- [Main layout](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/layout/MainLayout.tsx): `frontend/src/layout/MainLayout.tsx`

### Identity and chat

- [Chat page](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/chat/ChatPage.tsx): `frontend/src/pages/chat/ChatPage.tsx`
- [Chat user list](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/chat/components/UsersList.tsx): `frontend/src/pages/chat/components/UsersList.tsx`
- [Auth provider](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/providers/AuthProvider.tsx): `frontend/src/providers/AuthProvider.tsx`
- [Auth state](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/stores/useAuthStore.ts): `frontend/src/stores/useAuthStore.ts`
- [Chat state](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/stores/useChatStore.ts): `frontend/src/stores/useChatStore.ts`
- [User and messages](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/user.controller.js): `backend/src/controller/user.controller.js`
- [Realtime socket](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/lib/socket.js): `backend/src/lib/socket.js`

### Catalog and administration

- [Admin console](https://github.com/moses-tec/spotify-clone/blob/main/frontend/src/pages/admin/AdminPage.tsx): `frontend/src/pages/admin/AdminPage.tsx`
- [Song queries](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/song.controller.js): `backend/src/controller/song.controller.js`
- [Album queries](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/album.controller.js): `backend/src/controller/album.controller.js`
- [Catalog management](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/admin.controller.js): `backend/src/controller/admin.controller.js`
- [Catalog statistics](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/controller/stat.controller.js): `backend/src/controller/stat.controller.js`

### Backend runtime and data

- [HTTP server](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/index.js): `backend/src/index.js`
- [Song routes](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/routes/song.route.js): `backend/src/routes/song.route.js`
- [Album routes](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/routes/album.route.js): `backend/src/routes/album.route.js`
- [Admin routes](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/routes/admin.route.js): `backend/src/routes/admin.route.js`
- [Song records](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/song.model.js): `backend/src/models/song.model.js`
- [Album records](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/album.model.js): `backend/src/models/album.model.js`
- [User records](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/user.model.js): `backend/src/models/user.model.js`
- [Message records](https://github.com/moses-tec/spotify-clone/blob/main/backend/src/models/message.model.js): `backend/src/models/message.model.js`

### Other components

- **Listener**
- **Cloudinary**
- **Clerk identity**
- **MongoDB**

## Connections

- Listener → App routes: uses (evidence: `frontend/src/App.tsx`)
- App routes → Home discovery: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Album view: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Chat page: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Admin console: routes to (evidence: `frontend/src/App.tsx`)
- App routes → Main layout: wraps (evidence: `frontend/src/App.tsx`)
- Main layout → Playback controls: renders (evidence: `frontend/src/layout/MainLayout.tsx`)
- Chat page → Chat user list: renders (evidence: `frontend/src/pages/chat/ChatPage.tsx`)
- Auth provider → Auth state: checks admin (evidence: `frontend/src/providers/AuthProvider.tsx`)
- Auth provider → Chat state: starts socket (evidence: `frontend/src/providers/AuthProvider.tsx`)
- Auth provider → Clerk identity: gets token (evidence: `frontend/src/providers/AuthProvider.tsx`)
- HTTP server → Song routes: mounts routes (evidence: `backend/src/index.js`)
- HTTP server → Album routes: mounts routes (evidence: `backend/src/index.js`)
- HTTP server → Admin routes: mounts routes (evidence: `backend/src/index.js`)
- Song routes → Song queries: dispatches (evidence: `backend/src/routes/song.route.js`)
- Album routes → Album queries: dispatches (evidence: `backend/src/routes/album.route.js`)
- Admin routes → Catalog management: dispatches (evidence: `backend/src/routes/admin.route.js`)
- Song queries → Song records: queries (evidence: `backend/src/controller/song.controller.js`)
- Album queries → Album records: queries (evidence: `backend/src/controller/album.controller.js`)
- Catalog management → Song records: writes (evidence: `backend/src/controller/admin.controller.js`)
- Catalog management → Album records: writes (evidence: `backend/src/controller/admin.controller.js`)
- Catalog management → Cloudinary: uploads media (evidence: `backend/src/controller/admin.controller.js`)
- Catalog statistics → Song records: counts and aggregates (evidence: `backend/src/controller/stat.controller.js`)
- Catalog statistics → Album records: counts and aggregates (evidence: `backend/src/controller/stat.controller.js`)
- Catalog statistics → User records: counts (evidence: `backend/src/controller/stat.controller.js`)
- User and messages → User records: queries (evidence: `backend/src/controller/user.controller.js`)
- User and messages → Message records: queries (evidence: `backend/src/controller/user.controller.js`)
- HTTP server → Realtime socket: initializes (evidence: `backend/src/index.js`)
- Realtime socket → Message records: uses (evidence: `backend/src/lib/socket.js`)
- HTTP server → MongoDB: connects (evidence: `backend/src/index.js`)
- Song records → MongoDB: stores records
- Album records → MongoDB: stores records
- User records → MongoDB: stores records
- Message records → MongoDB: stores records
