# nishantnsut27/notify-music architecture

> Architecture diagram of the GitHub repository nishantnsut27/notify-music, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nishantnsut27/notify-music
- Repository: https://github.com/nishantnsut27/notify-music

## Overview

#### 1. Purpose and Deployment Shape
Notify Music is a full-stack streaming/discovery application: a React SPA provides playback, discovery, and library UX; an Express API owns authentication, persistence, provider orchestration, and user data. The frontend enters at `src/main.tsx` and `src/App.tsx`; the backend enters at `backend/src/index.ts`. Vercel hosts the SPA (`vercel.json`); the API is intended for a Node/Render runtime.

#### 2. Frontend Application and Client State
The React 19/Vite client renders route-like music, artist, album, discovery, authentication, and library experiences from `src/App.tsx` and `src/components/`. Zustand separates durable auth state, playback state, and notifications in `src/store/authStore.ts`, `src/store/playerStore.ts`, and `src/store/toastStore.ts`. API calls flow through `src/services/apiClient.ts`, which supports token refresh, then domain clients such as `src/services/musicApi.ts` and `src/services/userApi.ts`.

#### 3. Playback and Offline Boundary
Playback is centered on a singleton HTML5-audio-oriented hook, `src/hooks/usePlayer.ts`, consumed by UI controls and visualization components such as `src/components/PlayerControls.tsx` and `src/components/AudioVisualizer.tsx`. The browser Media Session and keyboard behavior remain client-side. PWA installation, service-worker policy, and offline rendering are isolated in `src/pwa/PwaProvider.tsx`, `src/pwa/InstallButton.tsx`, and `src/pwa/OfflinePage.tsx`; cached assets/API responses are an availability layer, not an alternate backend.

#### 4. HTTP API, Security, and Routing
Express composes security headers, CORS, body limits, rate/slowdown controls, validation, authentication, uploads, and centralized errors before route handlers. The main boundary is `backend/src/index.ts`; route groups are `backend/src/routes/authRoutes.ts`, `backend/src/routes/musicRoutes.ts`, and `backend/src/routes/userRoutes.ts`. JWT access/refresh authentication and request protection are enforced in `backend/src/middleware/auth.middleware.ts`, `backend/src/middleware/security.middleware.ts`, and `backend/src/middleware/rateLimit.middleware.ts`.

#### 5. Identity and User Library Persistence
Auth controllers/services implement registration, login, refresh rotation, verification OTPs, and password recovery through `backend/src/controllers/authController.ts` and `backend/src/services/authService.ts`. MongoDB/Mongoose persists users and their cloud-synced library records via `backend/src/models/user.model.ts`, `backend/src/models/playlist.model.ts`, and `backend/src/models/favorite.model.ts`. User operations are coordinated by `backend/src/controllers/userController.ts` and `backend/src/services/userService.ts`; avatar uploads cross to Cloudinary through `backend/src/services/cloudinaryService.ts`. Transactional verification/reset email crosses to Brevo via `backend/src/services/emailService.ts`.

#### 6. Music Search Provider Pipeline
`backend/src/controllers/musicController.ts` delegates music requests to `backend/src/services/musicService.ts`. The service queries JioSaavn first through `backend/src/providers/jiosaavnProvider.ts`; empty/error results invoke Jamendo through `backend/src/providers/jamendoProvider.ts`, behind the shared provider contract `backend/src/providers/musicProvider.interface.ts`. Provider-specific payloads are normalized in `backend/src/normalizers/musicNormalizer.ts`, then filtered, deduplicated, and ranked before a stable API response is returned. In-memory cache/request coalescing is handled by `backend/src/services/cacheService.ts`.

#### 7. Discovery and External Dependencies
Trending discovery is a separate orchestration stage in `backend/src/services/discoveryService.ts`, driven by curated terms in `backend/src/config/discoveryKeywords.ts`; it selects artists, invokes the same provider chain, filters relevance, and interleaves tracks. Recommendations similarly favor JioSaavn related content with Jamendo fallback. Material external systems are MongoDB, JioSaavn, Jamendo, Cloudinary, Brevo, and browser audio/PWA APIs; environment-backed application and database setup live in `backend/src/config/config.ts` and `backend/src/config/database.ts`.

Main entry points: [`backend/src/services/musicService.ts`](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/musicService.ts) (Music orchestration), [`src/main.tsx`](https://github.com/nishantnsut27/notify-music/blob/main/src/main.tsx) (SPA entry & routes), [`backend/src/index.ts`](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/index.ts) (API composition), [`backend/src/routes/musicRoutes.ts`](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/routes/musicRoutes.ts) (Music routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React SPA"]
  node_spa_entry["SPA entry &amp; routes<br/>React/Vite<br/>[main.tsx]"]
  node_client_state["Auth, player &amp; toast state<br/>Zustand stores<br/>[authStore.ts]"]
  node_api_client["API client<br/>HTTP client<br/>[apiClient.ts]"]
  node_playback["Playback controls<br/>HTML5 audio hook<br/>[usePlayer.ts]"]
  node_pwa["PWA availability layer<br/>PWA provider<br/>[PwaProvider.tsx]"]
end

subgraph group_api["Express API"]
  node_api_entry["API composition<br/>Express<br/>[index.ts]"]
  node_auth_routes["Auth routes<br/>Express routes<br/>[authRoutes.ts]"]
  node_music_routes["Music routes<br/>Express routes<br/>[musicRoutes.ts]"]
  node_user_routes["User routes<br/>Express routes<br/>[userRoutes.ts]"]
  node_auth_service["Identity service<br/>Auth service<br/>[authService.ts]"]
  node_user_service["Library service<br/>User service<br/>[userService.ts]"]
  node_music_service["Music orchestration<br/>Music service<br/>[musicService.ts]"]
  node_discovery_service["Discovery orchestration<br/>Discovery service"]
  node_cache["Request cache<br/>In-memory cache<br/>[cacheService.ts]"]
  node_normalizer["Result normalization<br/>Normalizer<br/>[musicNormalizer.ts]"]
end

subgraph group_providers["Music providers"]
  node_jiosaavn["JioSaavn adapter<br/>Provider adapter"]
  node_jamendo["Jamendo adapter<br/>Provider adapter<br/>[jamendoProvider.ts]"]
end

subgraph group_external["External systems"]
  node_mongodb[("MongoDB<br/>Database")]
  node_cloudinary["Cloudinary<br/>Media service"]
  node_brevo["Brevo<br/>Email service"]
  node_browser_apis["Browser audio &amp; PWA APIs<br/>Browser platform"]
end

node_spa_entry -->|"reads and updates"| node_client_state
node_spa_entry -->|"uses"| node_api_client
node_spa_entry -->|"drives"| node_playback
node_spa_entry -->|"wraps"| node_pwa
node_playback -->|"controls audio"| node_browser_apis
node_pwa -->|"uses service worker"| node_browser_apis
node_api_client -->|"HTTPS requests"| node_api_entry
node_api_entry -->|"mounts"| node_auth_routes
node_api_entry -->|"mounts"| node_music_routes
node_api_entry -->|"mounts"| node_user_routes
node_auth_routes -->|"auth actions"| node_auth_service
node_user_routes -->|"library actions"| node_user_service
node_music_routes -->|"search and playback data"| node_music_service
node_music_routes -->|"discovery requests"| node_discovery_service
node_auth_service -->|"users and tokens"| node_mongodb
node_auth_service -->|"verification and reset email"| node_brevo
node_user_service -->|"library records"| node_mongodb
node_user_service -->|"avatar uploads"| node_cloudinary
node_discovery_service -->|"uses provider pipeline"| node_music_service
node_music_service -->|"cache and coalesce"| node_cache
node_music_service -->|"query first"| node_jiosaavn
node_music_service -.->|"fallback on empty/error"| node_jamendo
node_jiosaavn -->|"provider payload"| node_normalizer
node_jamendo -->|"provider payload"| node_normalizer

click node_spa_entry "https://github.com/nishantnsut27/notify-music/blob/main/src/main.tsx"
click node_client_state "https://github.com/nishantnsut27/notify-music/blob/main/src/store/authStore.ts"
click node_api_client "https://github.com/nishantnsut27/notify-music/blob/main/src/services/apiClient.ts"
click node_playback "https://github.com/nishantnsut27/notify-music/blob/main/src/hooks/usePlayer.ts"
click node_pwa "https://github.com/nishantnsut27/notify-music/blob/main/src/pwa/PwaProvider.tsx"
click node_api_entry "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/index.ts"
click node_auth_routes "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/routes/authRoutes.ts"
click node_music_routes "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/routes/musicRoutes.ts"
click node_user_routes "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/routes/userRoutes.ts"
click node_auth_service "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/authService.ts"
click node_user_service "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/userService.ts"
click node_music_service "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/musicService.ts"
click node_discovery_service "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/discoveryService.ts"
click node_cache "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/cacheService.ts"
click node_normalizer "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/normalizers/musicNormalizer.ts"
click node_jiosaavn "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/providers/jiosaavnProvider.ts"
click node_jamendo "https://github.com/nishantnsut27/notify-music/blob/main/backend/src/providers/jamendoProvider.ts"

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_spa_entry,node_client_state,node_api_client,node_playback,node_pwa toneBlue
class node_api_entry,node_auth_routes,node_music_routes,node_user_routes,node_auth_service,node_user_service,node_music_service,node_discovery_service,node_cache,node_normalizer toneAmber
class node_jiosaavn,node_jamendo toneMint
class node_mongodb,node_cloudinary,node_brevo,node_browser_apis toneRose
```

## Components

### React SPA

- [SPA entry & routes](https://github.com/nishantnsut27/notify-music/blob/main/src/main.tsx): React/Vite · `src/main.tsx`
- [Auth, player & toast state](https://github.com/nishantnsut27/notify-music/blob/main/src/store/authStore.ts): Zustand stores · `src/store/authStore.ts`
- [API client](https://github.com/nishantnsut27/notify-music/blob/main/src/services/apiClient.ts): HTTP client · Refreshes access tokens before domain requests. · `src/services/apiClient.ts`
- [Playback controls](https://github.com/nishantnsut27/notify-music/blob/main/src/hooks/usePlayer.ts): HTML5 audio hook · Owns browser audio, Media Session, and keyboard playback behavior. · `src/hooks/usePlayer.ts`
- [PWA availability layer](https://github.com/nishantnsut27/notify-music/blob/main/src/pwa/PwaProvider.tsx): PWA provider · Caches assets and API responses for offline availability. · `src/pwa/PwaProvider.tsx`

### Express API

- [API composition](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/index.ts): Express · Applies security, validation, authentication, limits, uploads, and error handling. · `backend/src/index.ts`
- [Auth routes](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/routes/authRoutes.ts): Express routes · `backend/src/routes/authRoutes.ts`
- [Music routes](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/routes/musicRoutes.ts): Express routes · `backend/src/routes/musicRoutes.ts`
- [User routes](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/routes/userRoutes.ts): Express routes · `backend/src/routes/userRoutes.ts`
- [Identity service](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/authService.ts): Auth service · Registration, login, refresh rotation, OTP verification, and recovery. · `backend/src/services/authService.ts`
- [Library service](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/userService.ts): User service · Coordinates cloud-synced user library operations. · `backend/src/services/userService.ts`
- [Music orchestration](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/musicService.ts): Music service · Selects providers and returns stable music responses. · `backend/src/services/musicService.ts`
- [Discovery orchestration](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/discoveryService.ts): Discovery service · Builds trending and recommendation results from provider content. · `backend/src/services/discoveryService.ts`
- [Request cache](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/services/cacheService.ts): In-memory cache · Caches and coalesces provider requests. · `backend/src/services/cacheService.ts`
- [Result normalization](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/normalizers/musicNormalizer.ts): Normalizer · Filters, deduplicates, ranks, and stabilizes provider payloads. · `backend/src/normalizers/musicNormalizer.ts`

### Music providers

- [JioSaavn adapter](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/providers/jiosaavnProvider.ts): Provider adapter · Primary music provider. · `backend/src/providers/jiosaavnProvider.ts`
- [Jamendo adapter](https://github.com/nishantnsut27/notify-music/blob/main/backend/src/providers/jamendoProvider.ts): Provider adapter · Fallback music provider. · `backend/src/providers/jamendoProvider.ts`

### External systems

- **MongoDB**: Database · Persists users, playlists, and favorites through Mongoose.
- **Cloudinary**: Media service · Stores uploaded avatars.
- **Brevo**: Email service · Delivers verification and password-reset email.
- **Browser audio & PWA APIs**: Browser platform

## Connections

- SPA entry & routes → Auth, player & toast state: reads and updates
- SPA entry & routes → API client: uses
- SPA entry & routes → Playback controls: drives
- SPA entry & routes → PWA availability layer: wraps
- Playback controls → Browser audio & PWA APIs: controls audio
- PWA availability layer → Browser audio & PWA APIs: uses service worker
- API client → API composition: HTTPS requests
- API composition → Auth routes: mounts
- API composition → Music routes: mounts
- API composition → User routes: mounts
- Auth routes → Identity service: auth actions
- User routes → Library service: library actions
- Music routes → Music orchestration: search and playback data
- Music routes → Discovery orchestration: discovery requests
- Identity service → MongoDB: users and tokens
- Identity service → Brevo: verification and reset email
- Library service → MongoDB: library records
- Library service → Cloudinary: avatar uploads
- Discovery orchestration → Music orchestration: uses provider pipeline
- Music orchestration → Request cache: cache and coalesce
- Music orchestration → JioSaavn adapter: query first
- Music orchestration → Jamendo adapter: fallback on empty/error
- JioSaavn adapter → Result normalization: provider payload
- Jamendo adapter → Result normalization: provider payload