🎵 SoundStream – Music Streaming Backend

SoundStream is a Spotify-like backend application built using Spring Boot.
It models real-world music streaming concepts such as Songs, Artists, Albums, and Playlists, focusing on clean architecture, scalable REST APIs, and best practices with JPA/Hibernate.

This project is designed as a learning + portfolio project demonstrating production-grade backend patterns.

---

📑 Table of Contents

• Overview
• Architecture
• Tech Stack
• Features
• Project Structure
• API Design Principles
• Application Setup
• API Endpoints
• Future Enhancements
• License

---

📌 Overview

SoundStream provides RESTful APIs to manage music content:

• Songs belong to albums
• Songs can have multiple artists
• Artists can collaborate on multiple songs
• Playlists can contain songs from different albums and artists

The project emphasizes:

• DTO-based APIs (no entity exposure)
• Centralized exception handling
• ID-based relationships (no fragile name-based APIs)
• Clean service and repository layers
• Real-world Hibernate/JPA patterns

---

🏗 Architecture

+------------------------------+
| Client (Postman / Frontend) |
+------------------------------+
              |
              v
+------------------------------------+
| Spring Boot REST API (SoundStream) |
+------------------------------------+
              |
              v
+-------------------------------+
| PostgreSQL Database |
+-------------------------------+

---

🧰 Tech Stack

• Backend: Spring Boot (Java 17)
• ORM: Spring Data JPA (Hibernate)
• Database: PostgreSQL
• Build Tool: Gradle
• API Testing: Postman
• Logging: SLF4J + Logback
• Containerization: Docker (planned)

---

✨ Features

🎵 Songs

• Create songs using albumId and artistIds
• Fetch songs by ID
• Songs linked to albums and artists

🎤 Artists

• Create and manage artists
• Prevent duplicate artists (case-insensitive)
• Fetch artists with their songs

💿 Albums

• Create albums linked to artists
• Fetch albums and their songs

📃 Playlists

• Create playlists
• Add/remove songs from playlists
• Fetch playlists songs

---

📂 Project Structure

src/main/java/org/soundstream
├── controller
├── service
│ ├── songs
│ └── artists
│ └── albums
│ └── playlists
├── repository
├── model
├── dto
│ ├── request
│ └── response
├── mapper
├── exception
├── enum_
└── config

---

🔌 API Design Principles

• Versioned APIs: /api/v1/...
• DTO-based contracts
• No direct entity exposure
• Centralized exception handling using @ControllerAdvice
• Proper HTTP status codes
• ID-based relationships instead of name-based lookups

---

▶ Application Setup

1️⃣ Clone the repository

git clone https://github.com/your-username/soundstream.git
cd soundstream

2️⃣ Configure Database

Use environment variables for credentials:

spring.datasource.url=jdbc:postgresql://localhost:5432/soundstream
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

3️⃣ Run the application

./gradlew bootRun

Application will start at:

http://localhost:8080

🔗 API Endpoints

Songs

| Method | Endpoint | Description | | ------ | ---------------------------------------------------------------------- | ----------------------------------------------------------- | | POST | /api/v1/songs | Create songs | | GET | /api/v1/songs/{id} | Get songs by ID |

Artists

| Method | Endpoint | Description | | ------ | ---------------------------------------------------------------------- | ----------------------------------------------------------- | | POST | /api/v1/artists | Create artists | | GET | /api/v1/artists/{id} | Get artists by ID |

Albums

| Method | Endpoint | Description | | ------ | ---------------------------------------------------------------------- | ----------------------------------------------------------- | | POST | /api/v1/albums | Create albums | | GET | /api/v1/albums/{id} | Get albums by ID |

Playlists

| Method | Endpoint | Description | | ------ | ---------------------------------------------------------------------- | ----------------------------------------------------------- | | POST | /api/v1/playlists | Create playlists | | POST | /api/v1/playlists/{id}/songs/{songId} | Add songs to playlists | | GET | /api/v1/playlists/{id}/songs | Get playlists songs |

🚀 Future Enhancements

• Swagger / OpenAPI documentation
• Docker & docker-compose support
• Testcontainers for integration testing
• Role-based security (Spring Security)
• MapStruct for DTO mapping
• Load testing & N+1 query optimization
• Native image using GraalVM

📜 License

This project is licensed under the MIT License. See the LICENSE file for more details.

---