🎵 BeatShelf - Music Discovery Platform

Discover, Review, and Share Your Musical Journey

Live Demo • Documentation • Contributing • Support

---

📖 Table of Contents

• Overview
• Features
• Tech Stack
• Architecture
• Installation
• Configuration
• Usage
• API Documentation
• Database Schema
• Authentication
• Deployment
• Performance
• Contributing
• License
• Credits

---

🌟 Overview

BeatShelf is a full-stack music discovery platform built with Next.js 14 and the Spotify Web API. It allows users to discover new music, write in-depth reviews, rate songs, and curate personalized collections. Users can also generate visually stunning review cards that include the song's cover art, their rating, user ID, and review—perfect for sharing on Instagram Stories, Facebook, or any other social media platform.

🎯 Mission

Create a community-driven music discovery experience for exploring, reviewing, and sharing tracks.

🏆 Key Highlights

• Access to 50M+ songs via Spotify
• Real-time reviews and ratings
• Advanced search and social features
• Responsive, modern UI
• Generate stylish review cards to share on any social platform.

---

✨ Features

🎵 Music Discovery

• Search by song, artist, album, or genre
• Trending tracks, new releases, and charts
• Genre exploration and random discovery

👤 User Experience

• Personalized profiles with stats and activity
• Rich text reviews and 5-star ratings
• Favorites collection and dashboard
• Customizable settings
• Generate stylish review cards for sharing on social media

🔍 Advanced Features

• Real-time sync and dark theme
• Optimized performance and accessibility
• Intuitive navigation with animations and notifications

---

🛠 Tech Stack

Frontend

• Next.js 14 (App Router) with TypeScript
• Tailwind CSS, Radix UI, shadcn/ui
• Lucide React icons, React Context for state

Backend

• Node.js (Next.js API Routes)
• Supabase (PostgreSQL, Auth, Realtime, Storage)
• Spotify Web API

Tools

• npm, ESLint, Prettier, TypeScript
• Vercel for hosting and analytics

---

🏗 Architecture

The system uses a client-server model: Frontend (Next.js) interacts with Backend API Routes, which connect to Supabase for data/storage and Spotify for music data. Data flows from user interactions to API calls, database updates, and real-time UI syncs via Supabase Realtime.

Component Structure

• Pages/Components for UI
• Contexts/Hooks for state
• Utils/API Routes for logic

---

🚀 Installation

Prerequisites

• Node.js 18+, npm 9+, Git
• Supabase and Spotify accounts

Steps

# Clone the repo
git clone https://github.com/akshitsuthar/beatshelf.git && cd beatshelf

# Install dependencies
npm install

# Create environment file
touch .env.local

Add the following to .env.local

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_key
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret

# Run the development server
npm run dev

# Visit the app
http://localhost:3000

---

⚙️ Configuration

Supabase

• Create project in Supabase Dashboard
• Enable email auth
• Run SQL scripts for tables, policies, and functions (see scripts/ folder)

Spotify

• Create app in Spotify Developer Dashboard
• Note Client ID/Secret and set redirect URIs

Environment Variables

Variable	Description	Required
NEXT_PUBLIC_SUPABASE_URL	Supabase URL	✅
NEXT_PUBLIC_SUPABASE_ANON_KEY	Anon key	✅
SUPABASE_SERVICE_ROLE_KEY	Service key	✅
SPOTIFY_CLIENT_ID	Spotify ID	✅
SPOTIFY_CLIENT_SECRET	Spotify secret	✅

---

📱 Usage

Authentication

• Sign up at /auth/signup (email, username, password)
• Sign in at /auth/signin

Core Usage

• Search music: Use /search or API like /api/spotify/search?q=Beatles
• Write reviews: Go to /write-review, select song, rate, and publish
• Manage favorites: Heart icon on songs; view at /favorites
• Dashboard: View stats at /dashboard

---

🔌 API Documentation

Auth

• POST /api/auth/signup – Register new user

Music

• GET /api/spotify/search?q= – Search music
• GET /api/spotify/trending – Trending tracks
• GET /api/spotify/track/[id] – Song details

User

• GET /api/user/profile – Get user profile
• GET /api/user/reviews – Get user's reviews
• GET /api/user/favorites – Get favorite songs

---

🗄️ Database Schema

Tables

• profiles: Users (UUID, username, avatar)
• songs: Tracks (ID, name, artist, album)
• reviews: Reviews (UUID, user_id, song_id, content)
• ratings: Ratings (UUID, user_id, song_id, rating)
• favorites: Favorite songs (UUID, user_id, song_id)

Relationships

• One-to-Many (Users → Reviews, Ratings, Favorites)
• Indexed on user_id, song_id, artist_name for speed

---

🔐 Authentication

Flow: Register/login with email/password/username; JWT sessions via Supabase.

Security: RLS, password hashing, rate limiting.

Protected Routes: /dashboard, /write-review, /favorites, /settings.

Public Routes: /, /search, /song/[id], /trending.

---

🚀 Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

• Add environment variables in Vercel Dashboard
• Configure domain and HTTPS

// Build config
{
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "framework": "nextjs"
}

---

⚡ Performance

Optimizations: Code splitting, lazy loading, image optimization, API caching, database indexing.

Monitoring: Vercel Analytics for vitals and errors.

---

🤝 Contributing

Fork, clone, branch, change, test, PR.

Guidelines: Use TypeScript, follow code style, meaningful commits (e.g., "feat: add feature").

Areas: Bug fixes, features, docs, UI, performance.

Report issues on GitHub.

---

📄 License

This project is licensed under the MIT License.

© 2025 Akshit Suthar
See the full LICENSE file for more details.

🙏 Credits

Created by Akshit Suthar:

• Portfolio: Akshit Suthar
• LinkedIn: Akshitsuthar
• GitHub: github.com/akshitsutharr

Thanks to Spotify, Supabase, Vercel, Next.js, Tailwind, Radix UI, shadcn/ui.

Inspiration: Letterboxd, Spotify, Apple Music.

---

🎵 Made with ❤️ by Akshit Suthar

BeatShelf - Where Music Meets Community

⭐ Star if helpful!