Project Final: Melody Dive

University: University of Science, VNU-HCM

Course: Introduction to Software Engineering

Instructors: Mr. Ho Tuan Thanh, Ms. Nguyen Thi Minh Tuyen

Semester: 2025-2026, Semester 1

Melody Dive is a music streaming website that helps users search for and listen to songs. It also includes various features, such as allowing users to like and save their favorite tracks, share songs with others, etc.

Group Information

Class: 23CLC05

Group members:

1. Nguyen Hoang Anh Khoa - 23127015
2. Huỳnh Gia Bảo - 23127154
3. Nguyen Hoang Dang - 23127166
4. Ngo Tran Quang Dat - 23127341
5. Thai Minh Huy - 23127379

🛠 Tech Stack

💻 Backend

• Python

💻 Frontend

• HTML, CSS, JavaScript
• ReactJS

Project Structure

├── backend/
│   ├── main.py
│   ├── requirements.txt
│   └── app/
│       ├── api/
│       │   ├── api.py
│       │   ├── deps.py
│       │   └── endpoints/
│       ├── core/
│       │   ├── config.py
│       │   ├── security.py
│       │   └── semantic.py
│       ├── db/
│       │   ├── base.py
│       │   └── session.py
│       ├── models/
│       │   └── models.py
│       ├── schemas/
│       │   ├── album.py
│       │   ├── artist.py
│       │   ├── comments.py
│       │   ├── dashboard.py
│       │   ├── payment.py
│       │   ├── playlist.py
│       │   ├── premium.py
│       │   ├── report.py
│       │   ├── search.py
│       │   ├── song.py
│       │   ├── token.py
│       │   └── user.py
│       ├── scripts/
│       │   ├── data.sql
│       │   ├── fts_index.sql
│       │   ├── init.sql
│       │   ├── search_history.sql
│       │   ├── transaction.sql
│       │   └── update.sql
│       ├── services/
│       │   ├── albums.py
│       │   ├── artist.py
│       │   ├── auth.py
│       │   ├── comments.py
│       │   ├── dashboard.py
│       │   ├── files.py
│       │   ├── payment.py
│       │   ├── playlists.py
│       │   ├── premium.py
│       │   ├── reports.py
│       │   ├── search.py
│       │   ├── semantic_search.py
│       │   └── songs.py
│       └── utils/
│           └── card_validator.py
└── frontend/
    ├── index.html
    ├── package.json
    ├── vite.config.js
    ├── public/
    └── src/
        ├── App.jsx
        ├── main.jsx
        ├── assets/
        ├── components/
        ├── contexts/
        │   ├── AuthContext.jsx
        │   ├── MusicPlayerContext.jsx
        │   └── UserContext.jsx
        ├── controllers/
        ├── data/
        ├── hooks/
        ├── layouts/
        ├── pages/
        ├── routes/
        └── utils/

Getting Started

Prerequisites

• Node.js and npm
• Python and pip

Backend

1. Navigate to the backend directory:

   cd backend

2. Install the required packages:

   pip install -r requirements.txt

3. Run the backend server:

   uvicorn main:app --reload

Frontend

1. Navigate to the frontend directory:

   cd frontend

2. Install the required packages:

   npm install

3. Run the frontend development server:

   npm run dev

Detailed Folder Descriptions

Root Directory

• .git/: Contains the history and metadata for the Git version control system.
• backend/: Holds the source code for your backend server, which is a Python FastAPI application.
• frontend/: Contains the source code for your frontend web application, built with React.

Backend (backend/)

• main.py: FastAPI entrypoint; run with uvicorn main:app --reload after activating the virtual environment.
• requirements.txt: Python dependencies.
• app/: Main FastAPI package.
  • api/: Router assembly (api.py), dependencies (deps.py), premium middleware (premium.py), and feature-specific routers inside endpoints/.
  • core/: Configuration, security utilities, and semantic search helpers.
  • db/: Database setup files (session.py, base.py).
  • models/: SQLAlchemy models definition.
  • schemas/: Pydantic schemas for validation/serialization (albums, artists, comments, payments, playlists, premium, reports, search, songs, tokens, users, dashboards).
  • scripts/: SQL initialization and update scripts (data seeding, FTS index, transactions, search history).
  • services/: Business logic and service layer (auth, payment, playlists, search, semantic search, reports, etc.).
  • utils/: Shared utilities such as card validation.

Frontend (frontend/)

• public/: Static assets served as-is.
• src/: React app source.
  • App.jsx, main.jsx: Application bootstrap.
  • assets/: Styles and static client assets.
  • components/: Reusable UI building blocks.
  • contexts/: React context providers (auth, user, music player state).
  • controllers/: Frontend request helpers mapping to backend endpoints.
  • hooks/: Custom hooks (auth, audio player, debounce, fetch helpers, etc.).
  • layouts/: Layout components (e.g., admin/auth shells).
  • pages/: Page-level components.
  • routes/: Routing definitions.
  • utils/: Client-side helpers and constants.

How to run the code

Backend

1. Create virtual environment and install neccessary libraries: Windows

   python -m venv fastapi_env
   .\fastapi_env\Scripts\activate 
   python -m pip install -r backend/requirements.txt

MacOS/Linux

python3 -m venv fastapi_env
source fastapi_env/bin/activate
pip install -r backend/requirements.txt

2. Run the code: Remember to activate the fastapi_env before running Backend code

   .\fastapi_env\Scripts\activate (For Windows)
   source fastapi_env/bin/activate (For MacOS/Linux)

After the venv is activated, move to backend/ and run the code

   cd backend
   uvicorn main:app --reload

3. Access the temporary GUI of backend by accessing the URL: localhost:8000/docs