Serena - Collaborative Radio Station Platform

Serena is a collaborative radio station platform that enables users to create and join virtual music stations for shared listening experiences. The application features a React frontend and Spring Boot backend, integrating with the Spotify API to provide real-time music playback and queue management.

🎵 Features

• Create & Join Stations: Users can create radio stations with unique join codes or join existing stations
• Collaborative Queuing: Multiple users can add songs to their preferred queues
• Intelligent Recommendations: Advanced algorithm considers song popularity, tempo similarity, audio features, and user preferences
• Real-time Playback: Spotify integration for seamless music streaming (station owners control playback)
• User Authentication: JWT-based authentication system with owner and client roles
• Responsive UI: Modern React interface with animated backgrounds and intuitive controls

🏗️ Architecture

Backend (Spring Boot)

• Language: Java
• Framework: Spring Boot
• Authentication: JWT tokens
• Queue Algorithm: Multi-factor recommendation system
• API: RESTful endpoints for station and queue management

Frontend (React)

• Language: JavaScript (JSX)
• Framework: React 19.1.1
• Routing: React Router DOM
• Spotify Integration: Web Playback SDK
• Styling: CSS with animations

External APIs

• Spotify Web API: Music data and playback control
• Spotify Web Playback SDK: Browser-based music streaming

🚀 Quick Start

Prerequisites

• Node.js (v16+)
• Java 11+
• Gradle
• Docker (optional)
• Spotify Premium account (for playback control)

Backend Setup

cd backend
./gradlew bootRun

The backend will start on http://localhost:8080

Frontend Setup

cd frontend
npm install
npm start

The frontend will start on http://localhost:3000

Docker Setup (Alternative)

docker-compose up

📖 API Documentation

Detailed API documentation is available in backend/API_DOCUMENTATION.md.

Key Endpoints

• POST /api/radio-stations - Create a new radio station
• GET /api/radio-stations - List all radio stations
• POST /api/clients/connect - Join a station with join code
• POST /api/songs/queue - Add song to client's preferred queue
• GET /api/songs/queue/recommended - Get intelligently sorted queue

🎯 How It Works

Station Creation

1. User creates a station with name and description
2. System generates unique station ID and 6-character join code
3. Creator becomes the station owner with playback control

Joining Stations

1. Users join with the station's join code
2. Receive client authentication token
3. Can add songs to their preferred queue

Queue Algorithm

The intelligent queue system considers:

• Preferred Queue Position (30%): User song preferences
• Popularity (20%): Spotify popularity scores
• Tempo Similarity (20%): BPM matching with current song
• Audio Features (30%): Danceability, energy, valence, etc.

Playback Control

• Only station owners can control playback
• Automatic progression through recommended queue
• Real-time sync with Spotify Web Playback SDK

🔧 Configuration

Backend Configuration

Update backend/src/main/resources/application.properties:

# Add your Spotify credentials and other settings

Frontend Configuration

Update Spotify credentials in frontend/src/constants/ApiConstants.js

🧪 Testing

Backend Tests

cd backend
./gradlew test

Frontend Tests

cd frontend
npm test