nishantnsut27/notify-music

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.