CourseMatcher - Setup Guide

This project is a full-stack web application for comparing university courses using Open AI-powered semantic matching. It includes a FastAPI backend and a React frontend

---

Prerequisites

Before starting, ensure you have the following installed:

• Python 3.11+
• Node.js + npm

Also please review the file structure documentation for this project if you are a new contributer:

https://github.com/OtagoPolytechnic/CourseMatcher/wiki/File-Structure-Documentation

---

🚀 Project Setup Instructions

1️⃣ Clone the repository

git clone https://github.com/OtagoPolytechnic/CourseMatcher.git
cd CourseMatcher

2️⃣ Run the automated setup script from the project root directory

⚠️ Important

• Before running the setup script, open the requirements.txt file located in the backend directory. Replace the following dependency line:

With:

Why?

The first dependency (2.4.0+cpu) is used only by Render during deployment to install the lightweight CPU-only version of PyTorch, avoiding timeouts caused by large CUDA packages. The second version (2.7.1) is for local development, where CUDA packages can safely be installed — though it may take longer to complete.

⚠️ Note:

Do not commit or push the torch==2.7.1 version requirements.txt file to the main branch. Keep this modification local to prevent deployment issues on Render. If needed, you can revert or manage the switch manually depending on your development environment.

You can then run:

./setup.bat

This script does all of the following:

Sets up a virtual environment for the backend

• Installs all backend Python dependencies
• Installs all frontend npm packages
• Creates a default .env file in the backend
• Creates a default .env file in the frontend

3️⃣ Add your OpenAI API key to the .env file

Ensure that you are able to run both the frontend and the backend simultaneously. In VS Code you can open two terminals and run FastAPI from one while using the other to run React's frontend.

4️⃣ Running the FastAPI server

From the backend/ folder ensure that the virtual environment activated

venv\Scripts\activate

Then run

uvicorn app.main:app --reload

Navigate to http://127.0.0.1:8000. The courses endpoint can be found at http://localhost:8000/courses/

5️⃣ Running the React frontend

From the frontend/ folder simply run npm run dev

Deployed API: https://coursematcher-api.onrender.com/courses/

Deployed Web Service: https://coursematcher-web.onrender.com/

⚠️ Note:

The services are deployed using a free instance of Render. For that reason, the API service will go into a sleep mode if requests are not being actively made to it within a certain timeframe. If the service hasn't been accessed in a while, it could take a while to spin up and load the courses data.