Skip to content

README.md

Latest commit

 

History

History
129 lines (98 loc) · 5.29 KB

README.md

File metadata and controls

129 lines (98 loc) · 5.29 KB
Raw

SoundSoulmate – Personalized Music Discovery App (Full-Stack Java + Android)

SoundSoulmate is a full-stack mobile application that personalizes music recommendations based on user preferences and real-time Spotify data. Built with Android (Java) on the client side and Spring Boot on the backend, the app enables users to enter a seed song and receive curated suggestions via a custom-built recommendation engine. It includes Spotify OAuth integration, live chat via WebSockets, and user analytics for enhanced engagement.

Developed collaboratively using a structured development lifecycle, the project balances recommendation accuracy, responsive UI, and foundational security practices.

Security-Conscious Design Principles

  • Spotify OAuth Integration
    Implements secure OAuth 2.0 token handling and session validation to ensure user account protection when linking Spotify.

  • Scoped API Access
    All Spotify and internal API calls are scoped by access token, ensuring least-privilege design in both music data retrieval and user profile interaction.

  • WebSocket Session Control
    Chat system enforces authenticated WebSocket connections and isolates messages between authorized users to prevent spoofing or cross-user injection.

  • Firebase Data Validation Rules
    Realtime database access is protected by authentication state and structured path-level access control to enforce proper authorization.

  • Input Validation & Data Sanitization
    Backend endpoints apply strict validation for all song, user, and message inputs to mitigate injection and data integrity issues.

Features

  • Personalized Music Recommendations
    Input a song to receive curated tracks using a Recurrent Recommender Network (RRN)-based logic trained on user preference patterns.

  • Spotify Account Linking
    Authenticate via Spotify to import top artists, saved tracks, and allow playlist creation or modification directly from the app.

  • Real-Time Chat System
    In-app messaging system allows users to chat with friends using secure WebSocket communication.

  • User Profiles & Analytics
    Users can view personalized music stats including top songs, listening history, and discovery preferences.

  • Social Discovery & Matching
    Browse other users’ profiles and connect based on shared music tastes and interaction history.

Architecture Overview

Frontend

  • Platform: Android (Java, XML Layouts)
  • Features:
    • Spotify login and token handling
    • Input interface for music discovery
    • Playlist interaction and display
    • Gesture controls and user profile views

Backend

  • Platform: Spring Boot (Java)
  • Database: Firebase Realtime Database
  • Components:
    • REST endpoints for music discovery and profile access
    • WebSocket server for chat and live communication
    • Spotify OAuth 2.0 token exchange and API proxying
    • RRN-based recommendation module for song selection

Setup Instructions

Android Frontend

  1. Clone the repository: 
    git clone https://github.com/GrantPierce94/SoundSoulmate.git

Open /Frontend in Android Studio Sync Gradle and run the app using an Android emulator or device

Backend Server Install Java 11+ Configure Firebase credentials and environment variables Navigate to /Backend and build: ./gradlew build java -jar build/libs/soundsoulmate-server.jar

Project Structure

├── Frontend/              # Android app
│   ├── activities/        # Login, Discovery, Profile, Chat
│   ├── services/          # Spotify access, chat client
│   └── ui/                # Layouts and screen flows
│
├── Backend/               # Spring Boot server
│   ├── controllers/       # REST endpoints
│   ├── services/          # Recommender logic and chat handling
│   └── spotify/           # OAuth integration and API proxy
│
├── sql/                   # Firebase rules and mock data (if applicable)
└── README.md              # Project documentation

Development & Testing Workflow Manual black-box testing on emulators and devices Token lifecycle and authentication failure testing Spotify API mock testing GitHub Actions CI/CD for backend builds and linting Milestone-driven waterfall development process

Tools & Technologies Frontend: Android SDK, Java, XML Layouts Backend: Spring Boot, REST APIs, WebSockets Database: Firebase Realtime Database Integrations: Spotify Web API (OAuth 2.0) CI/CD: GitLab Version Control: Git + GitHub

Project Management: GitHub Projects, milestone planning

Contributors

  • Grant Pierce (GitHub: @GrantPierce94) – Backend & DevOps Lead

    • Integrated Spotify OAuth and playlist functionality
    • Developed backend services and deployed CI/CD pipelines
    • Led application packaging and system testing

  • Jack – Frontend Developer & Chat System Engineer

    • Built Android UI for login, chat, and profile components
    • Implemented real-time WebSocket chat system
    • Designed swipe/gesture-based music interface

  • Danny – Backend Developer

    • Developed RRN logic for personalized song suggestions
    • Tuned backend responses and Firebase schema
    • Contributed to model training and testing

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