🎵 TuneBox

TuneBox is a full-stack music streaming app with React (Vite) on the frontend and Spring Boot + Neo4j on the backend.

🛠️ Tech Stack

• Frontend: React 19, TypeScript, Vite 7, Tailwind CSS 4, TanStack Query/Table, Radix UI
• Backend: Spring Boot 4.0.3, Java 21, Spring Security, Spring Data Neo4j, Spring Data Elasticsearch
• Data/Search: Neo4j 5.16 + APOC, Elasticsearch 9.2.1
• Infra: Docker Compose (backend stack), Nginx (production reverse proxy)

📁 Project Layout

TuneBox/
├─ backend/         # Spring Boot API, Docker Compose files, Neo4j seed files
├─ frontend/        # Vite React app
├─ media/           # songs + images mounted into backend
├─ nginx/           # nginx.conf used in production stack
└─ README.md

✨ Special Features

• Adaptive stream quality per user: /songs/stream/{songId} resolves low|normal|high variants from user settings; guests default to high.
• User audio preferences: audioQuality and volumeCapacity are persisted via /users/* settings APIs.
• Similar songs experience: backend query excludes the current song and returns top 5 similar tracks; song detail renders compact cards.
• Genre-first song browsing: Songs page groups genres alphabetically and shows vertical genre sections with left-aligned cards.
• Admin management UX: Manage Songs/Artists/Playlists tables display 20 rows per page with reliable Previous/Next disabled states.
• Live auth-aware UI: frontend dispatches/listens to tunebox-auth-changed so admin/sidebar/profile states update on login/logout without refresh.
• Playback continuity: global player state is context-driven, and layout bottom padding reacts immediately when a song starts/stops.
• Search + recommendations: Elasticsearch-backed /search plus personalized and un-personalized recommendation endpoints.

🚀 Quick Start (Development)

1. Configure backend environment:

cd backend
cp .env.example .env

2. Start backend stack (Neo4j + Elasticsearch + backend):

npm run dev

3. (Optional) Start dev stack with Neo4j seed job:

npm run dev:seed

4. Start frontend:

cd ../frontend
npm install
npm run dev -- --host --port 5173

Default URLs:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8080
• Neo4j Browser: http://localhost:7474
• Elasticsearch: http://localhost:9200

💻 Common Commands

Backend (backend/):

• npm run dev / npm run dev:seed
• npm run dev:down / npm run dev:clean
• npm run test
• npm run prod / npm run prod:seed / npm run prod:down

Frontend (frontend/):

• npm run dev
• npm run build
• npm run preview

🏭 Production Notes

• Production stack (backend/docker-compose.prod.yml) runs neo4j, backend, elasticsearch, and nginx.
• nginx serves built frontend files from frontend/dist.
• Production seed is manual through npm run prod:seed (uses backend/neo4j/prod-seed.cypher).

📚 Additional Docs

• Backend details: backend/README.md
• Frontend details: frontend/README.md

📄 License

This project is licensed under the MIT License. See LICENSE.