SonarPoppy (Back-end)

Webservice for Poppy and SonarPop

🌐 Check out the live version: http://145.24.237.95:8000/

Table of Contents

1. About this project
2. Functionality
3. Getting started
   1. Requirements
   2. Installation
4. How does it work?
   1. Technologies
   2. Entity Relationship Diagram
   3. Usage
5. License

ℹ️ About this project

SonarPoppy is an ethical AI recommender system that provides users with personalized recommendations while adhering to ethical guidelines.

This project was created for the third Tailored Learning Environment (Year 2) at Rotterdam University of Applied Sciences. The goal of the project was to create an ethical AI recommender system while working in two seperate teams: a front-end team and a back-end team.

Important

This repository only contains the back-end of this project! The front-end repositories can be found here (Poppy) and here (SonarPop).

Note

Read the documentation in the docs/ folder for more information about this project. Read the api documentation in docs/api-v1.md for more information about the API endpoints and their usage.

✨ Functionality

The back-end of SonarPoppy provides the following functionality:

• User authentication and management
• API key management for third-party access
• Feedback collection and processing for improving recommendations
• Integration with external APIs (Spotify, Last.fm) for music data
• Administrative interface for managing algorithm configurations and monitoring system performance
• Image management for artists and user profiles
• Social features such as friend management and sharing recommendations
• Comprehensive logging and error handling for maintainability and debugging
• Automated testing to ensure reliability and facilitate future development

🚀 Getting started

Below are the instructions on how to get the project running on your local machine!

Requirements

• Node.js & NPM
• MongoDB
• (Recommended) A REST client like Postman

Installation

1. Clone the repository

git clone https://github.com/Shav0nne/sonarpoppy.git sonarpoppy
cd sonarpoppy

2. Setup dependencies and back-end assets

npm install

• Copy and paste the following contents into a .env file (inside the express folder):

MONGODB_URI=mongodb://localhost:27017/sonarpoppy
EXPRESS_PORT=8000
BASE_URI=http://localhost:8000/api/v1
LASTFM_API_KEY=your_lastfm_api_key_here
SPOTIFY_CLIENT_ID=your_spotify_client_id_here
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here
JWT_SECRET=your_jwt_secret_here

3. Setup local test server

npm run dev

• View the website by going to http://localhost:8000

🛠️ How does it work?

Below you can find the documentation of SonarPoppy (Back-end)!

Technologies

SonarPoppy (Back-end) uses the following technologies:

• 
• 
• 

Entity Relationship Diagram

erDiagram
    User ||--o{ ApiKey : "has"
    User ||--o{ Blacklist : "has (via userId string)"
    User ||--o{ Feedback : "gives (via userId string)"
    User ||--o{ Friend : "sends/receives"
    User ||--o{ GenreSliders : "has (via userId string)"
    User ||--o{ SliderPreset : "has (via userId string)"
    Track ||--o{ Feedback : "receives"

    User {
        ObjectId _id PK
        String username
        String email
        String password
        String role
        String spotifyId
        String status
        Boolean hasCompletedOnboarding
    }

    AlgorithmConfig {
        ObjectId _id PK
        Object hybridWeights
        Object feedbackMultipliers
        Object cfWeights
        Object profileEvolution
        Object playCount
        Array dialPresets
        String updatedBy
    }

    ApiKey {
        ObjectId _id PK
        ObjectId userId FK
        String name
        String prefix
        String keyHash
        Boolean active
    }

    ArtistImage {
        ObjectId _id PK
        String artist
        Array images
        Date fetchedAt
    }

    Blacklist {
        ObjectId _id PK
        String userId FK
        Array entries
    }

    Feedback {
        ObjectId _id PK
        String userId FK
        ObjectId trackId FK
        String action
        Number playCount
        Date lastPlayedAt
    }

    Friend {
        ObjectId _id PK
        ObjectId sender_user_id FK
        ObjectId receiver_user_id FK
        String status
        Date accepted_at
    }

    GenreSliders {
        ObjectId _id PK
        String userId FK
        Map sliders
        Array locked
    }

    SliderPreset {
        ObjectId _id PK
        String userId FK
        String name
        Map sliders
        Array locked
        Boolean isDefault
    }

    Track {
        ObjectId _id PK
        String title
        String artist
        String album
        Number duration
        Array genreVector
        String spotifyId
        String deezerId
        Array similarTracks
        Array similarArtists
    }

Loading

Usage

After installation, you can run the project using the following command:

npm run dev

This will start the server in watch mode. The server will restart automatically when you make changes to the code.

By default, the server runs on port 8000 (or whatever is defined in your .env file).

API Access

The API is accessible at /api/v1.

• Base URL: http://localhost:8000/api/v1
• Documentation: detailed API documentation can be found in docs/api-v1.md. You can also import docs/SonarPoppy.postman_collection.json into Postman for testing.

Demo & Testing Interfaces

The project includes several simple HTML pages in the public/ directory to facilitate testing and demonstration:

• General Demo: http://localhost:8000/demo.html
• API Key Management: http://localhost:8000/api-keys.html
• Image Upload Test: http://localhost:8000/test-image-upload.html
• User Images: http://localhost:8000/test-user-images.html
• Playback Test: http://localhost:8000/playback.html
• Spotify Player: http://localhost:8000/spotify-player.html

Running Tests

To run the automated test suite:

npm test

This uses the native Node.js test runner with experimental mocks enabled.

📜 License

The source code in this repository is licensed under the MIT License.