With the rise of personalized music streaming services, there is a growing need for systems that can recommend music based on users' emotional states. Realizing this need, Moodify is being developed by Son Nguyen in 2024 to provide personalized music recommendations based on users' detected emotions.

The Moodify project is an integrated emotion-based music recommendation system that combines frontend, backend, AI/ML models, and data analytics to provide personalized music recommendations based on user emotions. The application analyzes text, speech, or facial expressions and suggests music that aligns with the detected emotions.

Supporting both desktop and mobile platforms, Moodify offers a seamless user experience with real-time emotion detection and music recommendations. The project leverages React for the frontend, Django for the backend, and three advanced, self-trained AI/ML models for emotion detection. Data analytics scripts and Apache Spark and Hadoop are also used to visualize emotion trends and model performance. Users open recommended tracks in Deezer's free web player straight from the Results page 🎸🥁🎹.

This repo ships a Makefile that wraps every common dev / ops task. From the repo root:

make help               # menu of every target
make install            # install all four workspaces
make dev                # run backend + frontend together
make test               # run jest + django + pytest
make deploy-prod        # Modal deploy + Vercel deploy (web + api)
make perf-smoke         # k6 smoke against prod

Self-host paths (Kubernetes, AWS / GCP / OCI / Azure, Argo CD, Helm) live under terraform/ (modules: vpc, eks, gke, aks, rds, redis, s3, monitoring, argocd), helm/ (moodify-backend, moodify-frontend, monitoring umbrella), kubernetes/, argocd/, k8s-addons/, aws/ (terraform/, kubernetes/production/, iam/, cloudwatch/), gcp/ (terraform/, kubernetes/, monitoring/), oracle-cloud/, and nginx/ (modular edge with snippets/, scripts/, exporter/). Each directory has its own README. The canonical production path is Vercel + Modal — see DEPLOYMENT.md.

• 🎵 Overview
• 🌐 Live Deployment
• 🌟 Features
• 🔐 Passkeys (WebAuthn)
• 🛠️ Technologies
• 🖼️ User Interface
• 📂 Complete File Structure
• 🛠️ Getting Started
  • Prerequisites
  • Setup and Train AI/ML Models
  • Set Up the Backend
  • Install and Run the Frontend
• 📋 API Endpoints
  • User Endpoints
  • Passkey Endpoints (WebAuthn / FIDO2)
  • Emotion Detection Endpoints
  • Admin Interface Endpoints
  • Admin Interface
• 🚀 Backend APIs Documentation
• 🤖 About the AI/ML Models
  • AI/ML Models Overview
  • Training the AI/ML Models
  • Testing the AI/ML Models
  • Pre-Trained Models
• 📊 Analytics Scripts
• 📱 Mobile App Version
• 🔗 Load Balancing
• 🐳 Containerization
• ☸️ Kubernetes
• 🔗 Jenkins
• 🚀 OpenAPI Specification
• 🔧 Contributing
• 📝 License
• 📧 Contact

Moodify provides personalized music recommendations based on users' emotional states detected through text, speech, and facial expressions. It interacts with a Django-based backend, AI/ML models for emotion detection, and utilizes data analytics for visual insights into emotion trends and model performance.

graph TB
    subgraph "Client Layer"
        A[Web App - React]
        B[Mobile App - React Native]
    end

    subgraph "Load Balancer Layer"
        C[NGINX Load Balancer]
    end

    subgraph "Application Layer"
        D[Django Backend API]
        E[AI/ML Service - Flask]
    end

    subgraph "AI/ML Models"
        F[Text Emotion Model<br/>BERT-based]
        G[Speech Emotion Model<br/>CNN + LSTM]
        H[Facial Emotion Model<br/>ResNet50]
    end

    subgraph "External Services"
        I[Deezer Search API]
    end

    subgraph "Data Layer"
        J[(MongoDB)]
        K[(Redis Cache)]
        L[(MongoDB Atlas)]
    end

    subgraph "Analytics Layer"
        M[Apache Spark]
        N[Apache Hadoop]
        O[Data Visualization]
    end

    A -->|HTTPS| C
    B -->|HTTPS| C
    C -->|Load Balance| D
    D -->|REST API| E
    E --> F
    E --> G
    E --> H
    D -->|Fetch Music| I
    D --> J
    D --> K
    D --> L
    J -.->|Analytics| M
    M <--> N
    M --> O

    style A fill:#61DAFB
    style B fill:#61DAFB
    style C fill:#009639
    style D fill:#092E20
    style E fill:#000000
    style F fill:#FF6F00
    style G fill:#FF6F00
    style H fill:#FF6F00
    style I fill:#1DB954
    style J fill:#47A248
    style K fill:#DC382D
    style M fill:#E25A1C
    style N fill:#66CCFF

sequenceDiagram
    participant U as User
    participant FE as Frontend
    participant LB as Load Balancer
    participant BE as Backend API
    participant AI as AI/ML Service
    participant DB as MongoDB
    participant SP as Deezer API
    participant CH as Redis Cache

    U->>FE: Input (Text/Speech/Image)
    FE->>LB: Send Request
    LB->>BE: Route to Backend
    BE->>CH: Check Cache
    alt Cache Hit
        CH-->>BE: Return Cached Result
    else Cache Miss
        BE->>AI: Forward for Analysis
        AI->>AI: Process with ML Model
        AI-->>BE: Return Emotion
        BE->>SP: Request Music Recommendations
        SP-->>BE: Return Tracks
        BE->>DB: Store User History
        BE->>CH: Cache Result
    end
    BE-->>FE: Return Recommendations
    FE-->>U: Display Results

The Moodify app is currently live and deployed on Vercel. You can access the live app using the following link: https://moodify-app.vercel.app.

Feel free to also visit the backend at Moodify Backend API.

For your information, the front-end's production (deployment) branch is frontend-deployment/production, and the backend's production (deployment) branch is main-deployment-branch/production.

The Moodify project aims to provide the following features:

• 🎯 Online reinforcement learning — every user trains their own playlist ranker in real time. A "Was this right?" widget records per-user mood corrections, and 👍 / 👎 / open-in-Deezer signals feed a Thompson-Sampling contextual bandit over a Beta-Bernoulli posterior that re-ranks every subsequent recommendation list. Mood-calibration map kicks in after 3 same-direction corrections; bandit kicks in after 20 logged signals. New and anonymous users see the rule-based pipeline unchanged.
• 🔐 Passwordless sign-in with passkeys (WebAuthn / FIDO2) — users enroll multiple passkeys (Face ID, Touch ID, Windows Hello, Android screen lock, or a hardware security key) and sign in without a password. Passkeys are managed on a dedicated Account → Passkeys page (add, rename, delete), a styled prompt offers setup right after sign-up, and a verified assertion mints the same JWT pair as password login. See Passkeys (WebAuthn).
• User registration and login functionality.
• Input analysis through text, speech, and facial expressions.
• Real-time music recommendations based on emotion detection.
• Visualization of emotion detection results and user history.
• Data analytics scripts for emotion trends and model performance.
• AI/ML models for text, speech, and facial emotion detection.
• User profile management and customization.
• Mobile app version for seamless user experience.
• Progressive Web App (PWA) features for offline support.
• Admin panel for managing users, recommendations, and data analytics.
• And so much more!

All three layers are user-scoped and authentication-gated. The feedback endpoint is POST /api/feedback/ and accepts both {kind: "mood", ...} and {kind: "track", ...} payloads (see backend/openapi.yaml).

Moodify supports passwordless sign-in with passkeys (WebAuthn / FIDO2) layered on top of the existing JWT auth — passwords keep working unchanged.

• Multiple passkeys per account. Enroll a phone, a laptop, and a hardware security key; each is stored as its own credential.
• Manage them in-app. A dedicated Account → Passkeys page (the "Log Out" button becomes an Account dropdown when signed in → Passkeys / Log Out) lets users add, rename, and delete passkeys, with device + "Synced" badges and last-used times.
• Set-up prompt after sign-up. A styled, on-brand modal (never a browser alert) offers passkey creation right after registration.
• Usernameless login. The login screen has a "Sign in with a passkey" option that works with discoverable credentials — no username required.

How it works (each ceremony is two calls):

register/begin   →  server issues PublicKeyCredentialCreationOptions + a single-use flowId
                    (the user's existing passkeys go in excludeCredentials)
register/complete→  server verifies the attestation (py_webauthn) and stores the public key
login/begin      →  server issues PublicKeyCredentialRequestOptions + flowId
login/complete   →  server verifies the assertion, advances the signature counter,
                    and returns the same { access, refresh } JWT pair as /users/login/

The server-issued challenge is persisted as a single-use, expiring record keyed by the opaque flowId, so the two-step handshake works statelessly across serverless instances. Verification is delegated to the audited py_webauthn library; the login begin response never discloses whether a username exists.

Here is the list of technologies used in the Moodify project:

• React: For building the user interface.
• Axios: For making HTTP requests to the backend.
• Material UI: For styling and UI components.
• React Router: For client-side routing.
• Redux: For state management.
• Jest: For unit testing.
• React Testing Library: For testing React components.

• Django: For building the backend API.
• Django REST Framework (DRF): For creating RESTful APIs.
• MongoEngine: For MongoDB integration with Django.
• JWT: For user authentication and authorization.
• py_webauthn: For WebAuthn / FIDO2 passkey registration and assertion verification.
• Deezer API: For fetching music recommendations (free, keyless).
• Swagger: For API documentation.
• Redoc: For API documentation.
• Flask: For serving the AI/ML models as APIs.
• Gunicorn: For serving the Django application.
• NGINX: For load balancing and reverse proxy.

• MongoDB: For storing user data and music recommendations.
• Redis: For caching and session management.
• PostgreSQL: For production database (optional, can be configured).

• PyTorch: For building and training AI/ML models.
• TensorFlow: For building and training AI/ML models.
• Keras: For building and training AI/ML models.
• HuggingFace: For using pre-trained models and transformers.
• Pandas: For data manipulation and analysis.
• Scikit Learn: For machine learning algorithms.
• NumPy: For numerical computations.
• MLflow: For tracking experiments and managing models.
• FER: For facial emotion recognition.

• Matplotlib: For data visualization.
• Apache Hadoop: For big data processing and analytics.
• Apache Spark: For distributed data processing and analytics.
• PySpark: For using Spark with Python.

• React Native: For building the mobile application.
• Expo: For building and deploying the React Native app.
• Expo Go: For testing the React Native app on mobile devices.

• Docker: For containerizing the application.
• Kubernetes: For orchestrating the containers.
• Jenkins: For continuous integration and deployment.
• Vercel: For hosting the Django API and React frontend.
• Modal: For hosting the ML inference service (memory snapshots, scale-to-zero).
• Vercel: For hosting the frontend application.
• Netlify: For hosting the frontend application (backup).
• GitHub Actions: For automating CI workflows and deployments.
• Docker Compose: For managing multi-container application.

Polished with WebGL + Three.js + React Three Fiber 3D components for a wonderful & appealing user experience!

The project has a comprehensive file structure combining frontend, backend, AI/ML models, and data analytics components:

Moodify-Emotion-Music-App/
├── frontend/                      # React frontend for the web application
│   ├── public/
│   │   ├── index.html             # Main HTML file
│   │   ├── manifest.json          # Web app manifest
│   │   └── favicon.ico            # Favicon for the app
│   │
│   ├── src/
│   │   ├── components/            # Contains all React components
│   │   ├── pages/                 # Contains main pages of the app
│   │   ├── styles/                # Contains global styles and themes
│   │   ├── context/               # Contains React Context API
│   │   ├── App.js                 # Main App component
│   │   ├── index.js               # Entry point for React
│   │   └── theme.js               # Material UI theme configuration
│   │ 
│   ├── .gitignore                 # Git ignore file
│   ├── Dockerfile                 # Dockerfile for containerization
│   ├── package.json               # NPM dependencies and scripts
│   └── README.md                  # Project documentation
│ 
├── backend/                       # Django backend for API services and database management
│   ├── manage.py                  # Django's command-line utility
│   ├── requirements.txt           # Backend dependencies
│   ├── backend/
│   │   ├── settings.py            # Django settings for the project
│   │   ├── urls.py                # URL declarations for the project
│   │   ├── users/                 # User management components
│   │   └── api/                   # Emotion detection and recommendation APIs
│   │
│   ├── .gitignore                 # Git ignore file
│   ├── Dockerfile                 # Dockerfile for containerization
│
├── ai_ml/                         # AI/ML models for emotion detection
│   ├── data/                      # Datasets for training and testing
│   ├── models/                    # Trained models for emotion detection
│   ├── src/                       # Source files for emotion detection and recommendation
│   │   ├── api/                   # API scripts for running emotion detection services
│   │   ├── recommendation/        # Music recommendation logic
│   │   └── data_processing/       # Data preprocessing scripts
│   │
│   ├── Dockerfile                 # Dockerfile for containerization
│   └── README.md                  # AI/ML documentation
│
├── data_analytics/                # Data analytics scripts and visualizations
│   ├── emotion_distribution.py    # Script for visualizing emotion distribution
│   ├── training_visualization.py  # Script for visualizing training and validation metrics
│   ├── predictions_analysis.py    # Script for analyzing model predictions
│   ├── recommendation_analysis.py # Script for visualizing music recommendations
│   ├── spark-hadoop/              # Spark and Hadoop integration scripts
│   └── visualizations/            # Generated visualizations
│
├── kubernetes/                    # Kubernetes deployment files
│   ├── backend-deployment.yaml    # Deployment file for the backend service
│   ├── backend-service.yaml       # Deployment file for the backend service
│   ├── frontend-deployment.yaml   # Deployment file for the frontend service
│   ├── frontend-service.yaml      # Deployment file for the frontend service
│   └── configmap.yaml             # ConfigMap for environment variables
│ 
├── aws/                           # AWS deployment and infrastructure as code (IaC) files
├── gcp/                           # GCP deployment and infrastructure as code (IaC) files
│
├── mobile/                        # React Native mobile application
│   ├── App.js                     # Main entry point for React Native app
│   ├── index.js                   # App registry for React Native
│   ├── package.json               # NPM dependencies and scripts
│   ├── components/                # React Native components
│   │   ├── Footer.js              # Footer component
│   │   ├── Navbar.js              # Header component
│   │   ├── Auth/                  # Authentication components (e.g., Login, Register)
│   │   └── Profile/               # Profile-related components
│   │
│   ├── context/                   # React Context API for state management
│   │   └── DarkModeContext.js     # Dark mode context provider
│   │
│   ├── pages/                     # Main pages of the app
│   │   ├── HomePage.js            # Home page component
│   │   ├── ProfilePage.js         # Profile page component
│   │   ├── ResultsPage.js         # Results page component
│   │   ├── LandingPage.js         # Landing page component
│   │   └── (and more...)
│   │
│   ├── assets/                    # Images, fonts, and other assets
│   ├── styles/                    # Styling files (similar to CSS for web)
│   ├── .gitignore                 # Git ignore file
│   ├── package.json               # Dependencies and scripts
│   └── README.md                  # Mobile app documentation
│
├── nginx/                         # NGINX configuration files (for load balancing and reverse proxy)
│   ├── nginx.conf                 # Main NGINX configuration file
│   └── Dockerfile                 # Dockerfile for NGINX container
│
├── images/                        # Images used in the README documentation 
├── docker-compose.yml             # Docker Compose file for containerization
└── README.md                      # Comprehensive README file for the entire project

• Node.js (v14 or higher)
• Python 3.8 or later
• MongoDB
• Virtual Environment (venv)
• .env File (for environment variables - you create your own credentials following the example file or contact me for mine.)

Start with setting up and training the AI/ML models, as they will be required for the backend to function properly.

Or, you can download the pre-trained models from the Google Drive links provided in the Pre-Trained Models section. If you choose to do so, you can skip this section for now.

1. Clone the repository:

   git clone https://github.com/hoangsonww/Moodify-Emotion-Music-App.git

2. Navigate to the AI/ML directory:

   cd Moodify-Emotion-Music-App/ai_ml

3. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate   # For macOS/Linux
   .\venv\Scripts\activate    # For Windows

4. Install dependencies:

   pip install -r requirements.txt

5. Edit the configurations in the src/config.py file:

   • Visit modal_inference/config.py if you need to override defaults. Music recommendations come from Deezer's public, keyless API -- no Spotify credential is required.
   • Visit the individual model training scripts in the src/models directory and update the paths to the datasets and output paths as needed.
   • Ensure all paths are correctly set before training the models!

6. Train the text emotion model:

   python src/models/train_text_emotion.py

   Repeat similar commands for other models as needed (e.g., facial and speech emotion models).

7. Ensure all trained models are placed in the models directory, and that you have trained all necessary models before moving to the next step!

8. Test the trained AI/ML models as needed:

   • Run the src/models/test_emotion_models.py script to test the trained models.
   • Ensure the models are providing accurate predictions before moving to the next step.

Once the AI/ML models are ready, proceed with setting up the backend.

1. Navigate to the backend directory:

   cd ../backend

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate   # For macOS/Linux
   .\venv\Scripts\activate    # For Windows

3. Install dependencies:

   pip install -r requirements.txt

4. Configure your secrets and environment:

   • Create a .env file in the backend directory.
   • Add the following environment variables to the .env file:

     SECRET_KEY=your_secret_key
     DEBUG=True
     ALLOWED_HOSTS=<your_hosts>
     MONGODB_URI=<your_mongodb_uri>
     # Passkeys / WebAuthn — defaults below work for local dev as-is.
     # In production set the RP id/origins to your FRONTEND domain.
     WEBAUTHN_RP_ID=localhost
     WEBAUTHN_RP_NAME=Moodify
     WEBAUTHN_EXPECTED_ORIGINS=http://localhost:3000,http://localhost:3001
     

   • Visit backend/settings.py and add SECRET_KEY & set DEBUG to True.

5. Run database migrations:

   python manage.py migrate

6. Start the Django server:

   python manage.py runserver

   The backend server will be running at http://127.0.0.1:8000/.

Finally, set up the frontend to interact with the backend.

1. Navigate to the frontend directory:

   cd ../frontend

2. Install dependencies using Yarn:

   npm install

3. Start the development server:

   npm start

   The frontend will start at http://localhost:3000.

Every ceremony is two calls — begin returns server options + an opaque flowId, complete posts the signed credential back. A verified login assertion returns the same {access, refresh} JWT pair as /users/login/.

Speech and facial uploads bypass Django and hit the Modal inference service directly with the user's JWT — see modal_inference/README.md for the direct-upload contract.

Both /metrics endpoints persist one row per request to a MongoDB Atlas time-series collection (30-day TTL), so trends survive container restarts and scale-to-zero. See modal_inference/README.md#sre-metrics and backend/README.md#sre-metrics for the full design (schema, resilience model, cost math).

The admin is local-only. It is gated behind ENABLE_ADMIN=True (auto-on whenever DEBUG=True). The Vercel deploy ships with ENABLE_ADMIN=False, so /admin/ returns 404 in production — by design, since production has no SQL database.

Production runs on Vercel with no SQL database, so the classic Django admin is intentionally disabled there. Locally it's a single env-flag away — flip it on, apply migrations once, create a superuser, and the familiar admin login page lives at /admin/.

1. Opt in (auto-on whenever DEBUG=True):

   export ENABLE_ADMIN=True       # or set DEBUG=True

2. One-time SQLite + admin tables:

   python manage.py migrate

3. Create a superuser:

   python manage.py createsuperuser

4. Run the server and open the admin:

   python manage.py runserver
   open http://127.0.0.1:8000/admin/

User-facing data (mood history, listening history, saved recommendations) lives in MongoDB Atlas and is managed through the REST API, not the admin. The admin only sees Django's own auth.User table — the superuser you create with createsuperuser.

Our backend APIs are all well-documented using Swagger UI and Redoc. You can access the API documentation at the following URLs:

• Swagger UI: https://moodify-backend-api.vercel.app/swagger/.
• Redoc: https://moodify-backend-api.vercel.app/redoc/.

Alternatively, you can run the backend server locally and access the API documentation at the following endpoints:

• Swagger UI: http://127.0.0.1:8000/swagger.
• Redoc: http://127.0.0.1:8000/redoc.

Regardless of your choice, you should see the following API documentation if everything is running correctly:

Swagger UI:

Redoc:

The AI/ML models are built using PyTorch, TensorFlow, Keras, and HuggingFace Transformers. These models are trained on various datasets to detect emotions from text, speech, and facial expressions.

The emotion detection models are used to analyze user inputs and provide real-time music recommendations based on the detected emotions. The models are trained on various datasets to capture the nuances of human emotions and provide accurate predictions.

• Text Emotion Detection: Detects emotions from text inputs.
• Speech Emotion Detection: Analyzes emotions from speech inputs.
• Facial Emotion Detection: Detects emotions from facial expressions.

The models are integrated into the backend API services to provide real-time emotion detection and music recommendations for users.

The models must be trained first before using them in the backend services. Ensure that the models are trained and placed in the models directory before running the backend server. Refer to the (Getting Started)[#getting-started] section for more details.

Examples of training the text emotion model.

To train the models, you can run the provided scripts in the ai_ml/src/models directory. These scripts are used to preprocess the data, train the models, and save the trained models for later use. These scripts include:

• train_text_emotion.py: Trains the text emotion detection model.
• train_speech_emotion.py: Trains the speech emotion detection model.
• train_facial_emotion.py: Trains the facial emotion detection model.

Ensure that you have the necessary dependencies, datasets, and configurations set up before training the models. Specifically, make sure to visit the config.py file and update the paths to the datasets and output directories to the correct ones on your system.

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

After that, you can run the test_emotion_models.py script to test the trained models and ensure they are providing accurate predictions:

python src/models/test_emotion_models.py

Alternatively, you can run the simple Flask API to test the models via RESTful API endpoints:

python ai_ml/src/api/emotion_api.py

The endpoints are as follows:

• /text_emotion: Detects emotion from text input
• /speech_emotion: Detects emotion from speech audio
• /facial_emotion: Detects emotion from an image
• /music_recommendation: Provides music recommendations based on the detected emotion

However, if training the model is too resource-intensive for you, you can use the following Google Drive links to download the pre-trained models:

• Text Emotion Detection Model - model.safetensors. Please download this model.safetensors file and place it into the ai_ml/models/text_emotion_model directory.
• Speech Emotion Detection Model - scaler.pkl. Please download this and place this into the ai_ml/models/speech_emotion_model directory.
• Speech Emotion Detection Model - trained_speech_emotion_model.pkl. Please download this and place this into the ai_ml/models/speech_emotion_model directory.
• Facial Emotion Detection Model - trained_facial_emotion_model.pt. Please download this and place this into the ai_ml/models/facial_emotion_model directory.

These have been pre-trained on the datasets for you and are ready to use in the backend services or for testing purposes once downloaded and correctly placed in the models directory.

Feel free to contect me if you encounter any issues or need further assistance with the AI/ML models.

The data_analytics folder provides data analysis and visualization scripts to gain insights into the emotion detection model's performance.

1. Run All Analytics Scripts:

   python data_analytics/main.py

2. View generated visualizations in the visualizations folder.

3. Here are some example visualizations:

Emotion Distribution Visualization

Training Loss Curve Visualization

There is also a fully-featured native mobile app built with React Native (Expo SDK 51). It runs from a single codebase on iOS 18+ and Android 15+, talks to the same Django REST API and Modal inference service as the web client, and ships with JWT auth, silent token refresh, mood-tinted theming, and graceful offline-degraded inference.

📘 Deep dive: see MOBILE_APPS.md for every screen, every diagram, and side-by-side iOS + Android captures. The short tour and dev setup live in mobile/README.md.

• Three inference modes — text, voice (.m4a), front-camera selfie.
• JWT auth with silent refresh — collapsed concurrent 401s, single in-flight refresh.
• Graceful degradation — Modal cold start or network failure still yields a curated fallback playlist (degraded: true).
• Auto-detected market from device locale (16 countries + Global).
• Per-mood gradient theming with 13 distinct mood palettes.
• Custom blurred pill tab bar floating above the content.

Login	Home — Text	Home — Voice	Home — Face

Results	Sort sheet	Market sheet	Profile

Settings	Edit email	Change password	Register

Forgot — Verify	Forgot — Reset

Explore — iOS	Explore — Android

flowchart LR
    subgraph Device[📱 iOS / Android]
        UI[React Native UI]
        Ctx[AuthContext]
        Store[(AsyncStorage)]
        Cam[expo-camera]
        Mic[expo-av]
    end
    UI --> Ax[Axios + interceptors]
    Ctx <--> Store
    Cam --> UI
    Mic --> UI
    Ax -- "auth, profile, history" --> API[Django REST API]
    Ax -- "text, audio, image" --> Modal[Modal inference]
    UI -- "open URL" --> Deezer[(Deezer search)]

cd mobile
npm install                              # or yarn install
cp .env.example .env                     # set EXPO_PUBLIC_API_URL / EXPO_PUBLIC_MODAL_API_URL
npx expo start                           # press i (iOS), a (Android), w (web), or scan the QR with Expo Go
# port collision?  npx expo start --port 8083

For production builds, use EAS Build — see mobile/README.md for the full flow.

Feel free to explore the mobile app and test its functionalities!

The project uses NGINX and Gunicorn for load balancing and serving the Django backend. NGINX acts as a reverse proxy server, while Gunicorn serves the Django application.

1. Install NGINX:

   sudo apt-get update
   sudo apt-get install nginx

2. Install Gunicorn:

    pip install gunicorn

3. Configure NGINX:

   • Update the NGINX configuration file (if needed) at /nginx/nginx.conf with your configuration.

4. Start NGINX and Gunicorn:

   • Start NGINX:

     sudo systemctl start nginx

   • Start Gunicorn:

     gunicorn backend.wsgi:application

5. Access the backend at http://<server_ip>:8000/.

Feel free to customize the NGINX configuration and Gunicorn settings as needed for your deployment.

The project can be containerized using Docker for easy deployment and scaling. You can create Docker images for the frontend, backend, and AI/ML models.

graph LR
    subgraph "Docker Compose Stack"
        subgraph "Application Containers"
            A[Frontend Container<br/>React:3000]
            B[Backend Container<br/>Django:8000]
            C[AI/ML Container<br/>Flask:5000]
        end

        subgraph "Database Containers"
            D[MongoDB Container<br/>:27017]
            E[Redis Container<br/>:6379]
        end

        subgraph "Infrastructure"
            F[NGINX Container<br/>:80]
        end
    end

    F -->|Proxy| A
    F -->|Proxy| B
    A -->|API Calls| B
    B -->|ML Requests| C
    B -->|Data| D
    B -->|Cache| E

    style A fill:#61DAFB
    style B fill:#092E20
    style C fill:#000000
    style D fill:#47A248
    style E fill:#DC382D
    style F fill:#009639

1. Build the Docker images:

   docker compose up --build

2. The Docker images will be built for the frontend, backend, and AI/ML models. Verify the images using:

   docker images

If you encounter any errors, try to rebuild your image without using the cache since Docker's cache may cause issues.

docker-compose build --no-cache

sequenceDiagram
    participant U as User
    participant FE as Frontend
    participant BE as Backend API
    participant DB as MongoDB
    participant JWT as JWT Service
    participant CH as Redis

    U->>FE: Login Request
    FE->>BE: POST /users/login/
    BE->>DB: Verify Credentials
    alt Valid Credentials
        DB-->>BE: User Found
        BE->>JWT: Generate Tokens
        JWT-->>BE: Access + Refresh Tokens
        BE->>CH: Cache Session
        BE-->>FE: Return Tokens
        FE->>FE: Store in localStorage
        FE-->>U: Redirect to Dashboard
    else Invalid Credentials
        DB-->>BE: User Not Found
        BE-->>FE: 401 Unauthorized
        FE-->>U: Show Error
    end

    Note over U,CH: Subsequent Requests
    U->>FE: Make Request
    FE->>BE: Request + Bearer Token
    BE->>CH: Validate Token
    alt Valid Token
        CH-->>BE: Token Valid
        BE->>BE: Process Request
        BE-->>FE: Return Data
    else Invalid Token
        CH-->>BE: Token Invalid
        BE-->>FE: 401 Unauthorized
        FE->>BE: Refresh Token
        BE->>JWT: Generate New Access Token
        JWT-->>BE: New Access Token
        BE-->>FE: Return New Token
        FE->>FE: Update Token
    end

Moodify uses Jest for backend API testing and Jest with React Testing Library for frontend component testing. The tests ensure that the APIs and components are functioning correctly.

The project includes unit tests for the backend APIs and AI/ML models. You can run the tests to ensure everything is working correctly.

1. Navigate to the backend directory:

   cd backend

2. Run the tests:

   pytest -q

This will run all the tests in the API and AI/ML model directories. Ensure that all tests pass before deploying the application.

The frontend also includes unit tests for the React components. You can run the tests using the following command:

cd frontend

# Run the frontend tests (default mode)
npm test

# Run the frontend tests in watch mode (will re-run tests on file changes)
npm test:watch

# Run the frontend tests in coverage mode (generates a coverage report)
npm test:coverage

This will run all the tests in the frontend directory and generate a coverage report. Ensure that all tests pass before deploying the frontend application.

Every screen in the app is covered by a snapshot test under frontend/src/__tests__/snapshots/ (one file per screen: Landing, Home, Profile, Results, Recommendations, Not Found, Forgot Password, Passkeys, Privacy Policy, and Terms of Service). Each renders the screen inside the providers it needs (dark-mode context, router, toast) and asserts the rendered markup with toMatchSnapshot(), so unintended UI changes surface in the diff. The committed baselines live in the adjacent __snapshots__/ directory.

cd frontend

# Run only the snapshot suite
npm test -- src/__tests__/snapshots

# Update the snapshots after an intentional UI change
npm test -- -u

After a deliberate UI change, run npm test -- -u to refresh the baselines, then commit the updated .snap files alongside your change.

We also added Kubernetes deployment files for the backend and frontend services. You can deploy the services on a Kubernetes cluster using the provided YAML files.

graph TB
    subgraph "Kubernetes Cluster"
        subgraph "Ingress Layer"
            ING[Ingress Controller<br/>NGINX]
        end

        subgraph "Service Layer"
            SVC1[Frontend Service<br/>ClusterIP]
            SVC2[Backend Service<br/>ClusterIP]
            SVC3[AI/ML Service<br/>ClusterIP]
            SVC4[MongoDB Service<br/>ClusterIP]
            SVC5[Redis Service<br/>ClusterIP]
        end

        subgraph "Deployment Layer"
            subgraph "Frontend Pods"
                FE1[Frontend Pod 1]
                FE2[Frontend Pod 2]
                FE3[Frontend Pod 3]
            end

            subgraph "Backend Pods"
                BE1[Backend Pod 1]
                BE2[Backend Pod 2]
                BE3[Backend Pod 3]
            end

            subgraph "AI/ML Pods"
                AI1[AI/ML Pod 1]
                AI2[AI/ML Pod 2]
            end

            subgraph "StatefulSets"
                DB1[MongoDB Pod]
                RD1[Redis Pod]
            end
        end

        subgraph "Storage Layer"
            PV1[(Persistent Volume<br/>MongoDB)]
            PV2[(Persistent Volume<br/>Models)]
        end

        subgraph "ConfigMaps & Secrets"
            CM[ConfigMap]
            SEC[Secrets]
        end
    end

    ING -->|Route /| SVC1
    ING -->|Route /api| SVC2
    SVC1 --> FE1 & FE2 & FE3
    SVC2 --> BE1 & BE2 & BE3
    SVC3 --> AI1 & AI2
    SVC4 --> DB1
    SVC5 --> RD1
    BE1 & BE2 & BE3 -->|Connect| SVC3
    BE1 & BE2 & BE3 -->|Connect| SVC4
    BE1 & BE2 & BE3 -->|Connect| SVC5
    DB1 --> PV1
    AI1 & AI2 --> PV2
    FE1 & FE2 & FE3 -.->|Config| CM
    BE1 & BE2 & BE3 -.->|Config| CM
    BE1 & BE2 & BE3 -.->|Credentials| SEC

    style ING fill:#009639
    style SVC1 fill:#326CE5
    style SVC2 fill:#326CE5
    style SVC3 fill:#326CE5
    style SVC4 fill:#326CE5
    style SVC5 fill:#326CE5
    style FE1 fill:#61DAFB
    style FE2 fill:#61DAFB
    style FE3 fill:#61DAFB
    style BE1 fill:#092E20
    style BE2 fill:#092E20
    style BE3 fill:#092E20
    style AI1 fill:#FF6F00
    style AI2 fill:#FF6F00
    style DB1 fill:#47A248
    style RD1 fill:#DC382D

1. Deploy the backend service:

   kubectl apply -f kubernetes/backend-deployment.yaml

2. Deploy the frontend service:

    kubectl apply -f kubernetes/frontend-deployment.yaml

3. Expose the services:

   kubectl expose deployment moodify-backend --type=LoadBalancer --port=8000
   kubectl expose deployment moodify-frontend --type=LoadBalancer --port=3000

4. Access the services using the LoadBalancer IP:

   • You can access the backend service at http://<backend_loadbalancer_ip>:8000.
   • You can access the frontend service at http://<frontend_loadbalancer_ip>:3000.

Feel free to visit the kubernetes directory for more information about the deployment files and configurations.

We have also included Jenkins pipeline script for automating the build and deployment process. You can use Jenkins to automate the CI/CD process for the Moodify app.

graph LR
    subgraph "Source Control"
        A[GitHub Repository]
    end

    subgraph "CI/CD Pipeline - GitHub Actions & Jenkins"
        B[Trigger on Push/PR]
        C[Run Tests]
        D[Build Docker Images]
        E[Security Scanning]
        F[Push to Registry]
        G[Deploy to Staging]
        H[Integration Tests]
        I[Deploy to Production]
    end

    subgraph "Container Registry"
        J[Docker Hub/ECR/GCR]
    end

    subgraph "Deployment Targets"
        K[Kubernetes Cluster]
        L[AWS/GCP]
        M[Vercel Frontend]
        N[Vercel Backend]
    end

    subgraph "Monitoring"
        O[Health Checks]
        P[Rollback on Failure]
    end

    A -->|Webhook| B
    B --> C
    C -->|Pass| D
    D --> E
    E -->|Pass| F
    F --> J
    J --> G
    G --> H
    H -->|Pass| I
    I --> K
    I --> L
    I --> M
    I --> N
    K & L & M & N --> O
    O -->|Failure| P
    P --> G

    style A fill:#181717
    style B fill:#2088FF
    style C fill:#34A853
    style D fill:#2496ED
    style E fill:#FF6B6B
    style F fill:#4CAF50
    style G fill:#FFA000
    style H fill:#34A853
    style I fill:#4CAF50
    style J fill:#2496ED
    style K fill:#326CE5
    style L fill:#FF9900
    style M fill:#000000
    style N fill:#46A2F1

stateDiagram-v2
    [*] --> CodeCommit
    CodeCommit --> BuildStage
    BuildStage --> TestStage
    TestStage --> SecurityScan
    SecurityScan --> BuildImages
    BuildImages --> PushRegistry
    PushRegistry --> StagingDeploy
    StagingDeploy --> IntegrationTest

    state TestStage {
        [*] --> UnitTests
        UnitTests --> IntegrationTests
        IntegrationTests --> E2ETests
        E2ETests --> [*]
    }

    state IntegrationTest {
        [*] --> HealthCheck
        HealthCheck --> SmokeTests
        SmokeTests --> [*]
    }

    IntegrationTest --> ApprovalGate
    ApprovalGate --> ProductionDeploy: Approved
    ApprovalGate --> [*]: Rejected

    state ProductionDeploy {
        [*] --> BlueGreenDeploy
        BlueGreenDeploy --> CanaryRelease
        CanaryRelease --> FullRollout
        FullRollout --> [*]
    }

    ProductionDeploy --> MonitoringAlerts
    MonitoringAlerts --> Healthy: All Clear
    MonitoringAlerts --> Rollback: Issues Detected

    Rollback --> StagingDeploy
    Healthy --> [*]

1. Install Jenkins on your server or local machine.

2. Create a new Jenkins pipeline job:

   • Create a new pipeline job in Jenkins.
   • Configure the pipeline to use the Jenkinsfile in the jenkins directory.

3. Run the Jenkins pipeline:

   • Run the Jenkins pipeline to build and deploy the Moodify app.
   • The pipeline will automate the build, test, and deployment process for the app.

Feel free to explore the Jenkins pipeline script in the Jenkinsfile and customize it as needed for your deployment process.

The backend APIs are documented using the OpenAPI Specification (OAS) format. The openapi.yaml file contains the API documentation in the OAS format, which can be used to generate client libraries, server stubs, and mock servers.

1. View the API Documentation

• Open Swagger Editor.
• Upload the openapi.yaml file or paste its content.
• Visualize and interact with the API documentation.

2. Test the API

• Import openapi.yaml into Postman:
  • Open Postman → Import → Select openapi.yaml.
  • Test the API endpoints directly from Postman.
• Or use Swagger UI:
  • Provide the file URL or upload it to view and test endpoints.

3. Generate Client Libraries

• Install OpenAPI Generator:

  npm install @openapitools/openapi-generator-cli -g

• Generate a client library:

  openapi-generator-cli generate -i openapi.yaml -g <language> -o ./client

• Replace <language> with the desired programming language.

4. Generate Server Stubs

• Generate a server stub:

  openapi-generator-cli generate -i openapi.yaml -g <framework> -o ./server

• Replace <framework> with the desired framework.

5. Run a Mock Server

• Install Prism:

  npm install -g @stoplight/prism-cli

• Start the mock server:

  prism mock openapi.yaml

6. Validate the OpenAPI File

• Use Swagger Validator:
  • Upload openapi.yaml or paste its content to check for errors.

This guide enables you to view, test, and utilize the API.

• Contributions are welcome! Feel free to fork the repository and submit a pull request.

• Note that this project is still under active development, and any contributions are appreciated.

• If you have any suggestions, feature requests, or bug reports, feel free to open an issue here.

• This project is licensed under the MIT License. Please see the LICENSE file for details.
• If you use or build upon this project, please provide the necessary attribution and references.

• Feel free to contact me at hoangson091104@gmail.com for any questions or feedback.
• You can also connect with me on LinkedIn.

Happy Coding and Vibin'! 🎶

Created with ❤️ by Son Nguyen in 2024.

🔝 Back to Top