team-5/README.md

# 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
```bash
cd backend
./gradlew bootRun
```

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

### Frontend Setup
```bash
cd frontend
npm install
npm start
```

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

### Docker Setup (Alternative)
```bash
docker-compose up
```

## 📖 API Documentation

Detailed API documentation is available in [`backend/API_DOCUMENTATION.md`](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`:
```properties
# Add your Spotify credentials and other settings
```

### Frontend Configuration
Update Spotify credentials in `frontend/src/constants/ApiConstants.js`

## 🧪 Testing

### Backend Tests
```bash
cd backend
./gradlew test
```

### Frontend Tests
```bash
cd frontend
npm test
```