This document provides all the necessary instructions for setting up the development environment, running the application, and deploying it to production.
This is a monorepo project built with the following core technologies:
- Frontend: React, TypeScript, Vite, Tailwind CSS, Shadcn
- Backend: Express.js, TypeScript, MongoDB, Mongoose
- Build & Tooling: pnpm Workspaces, ESLint, Prettier
- Deployment: GitHub Runners, Docker, Nginx
Before you begin, ensure you have the following tools installed on your system.
- Node.js (v22): If you have multiple Node.js version, it's recommended to use a version manager like nvm-windows. If you do install nvm, you must uninstall any existing Node.js installations to avoid conflicts.
- pnpm: Used for fast and efficient package management. Install it globally via npm:
npm install -g pnpm@latest
- MongoDB: Used as the database. Install it here. Make sure you do not install it as a service! You may not need MongoDB Compass (the GUI) if you prefer the VSCode MongoDB extension.
Clone the repository to your local machine and run the install command from the root of the project. This single command will install all dependencies for the entire monorepo (frontend, backend, and root).
# Clone the repository (replace with your actual repo URL)
git clone <your-repository-url>
cd <your-repository-name>
# Install all dependencies
pnpm installThis repository includes a .vscode/ directory with settings and extension recommendations to ensure a consistent development experience.
- Extensions: When you first open this project in VS Code, you should be prompted to install the recommended extensions. Please accept this prompt for the best experience.
- Settings: The
.vscode/settings.jsonfile contains project-specific settings for formatting (Prettier) and linting (ESLint) that will be applied automatically. You do not need to modify your global user settings.
Install Playwright browser dependencies (required for course scraping):
cd backend
pnpm exec playwright installcd backend
mkdir db_dataTo scrape course data, run:
cd backend
pnpm scrape:coursesThe most important commands are available as pnpm scripts in the root package.json. Run these from the root directory.
-
pnpm dev- Starts both the frontend and backend development servers in parallel.
-
pnpm build- Builds both the frontend and backend applications for production.
-
pnpm type-check- Runs the TypeScript compiler to check for type errors across the entire project.
-
pnpm lint- Lints all code in the project using ESLint.
-
pnpm format- Formats all code in the project using Prettier.
Run both frontend and backend dev servers from the root:
pnpm devIf you have issues, start each service in separate terminals:
# Terminal 1
cd backend
pnpm mongo
# Terminal 2
cd backend
pnpm dev
# Terminal 3
cd frontend
pnpm devTo run the scraper, see step 5 above.
The frontend runs at http://localhost:5173, backend API at port 8050.
Tip: In VS Code, press Ctrl + Shift + B to run the default build task (starts all dev servers and MongoDB).
This guide outlines how to build and run the application as a Docker container.
- Docker: The production server must have Docker installed.
- Reverse Proxy (Nginx): A reverse proxy like Nginx must be installed and configured on the host server to forward traffic to the application container's port.
From your project's root directory on the server, use Docker Compose to build and run the application:
docker compose -f infra/compose.yml up -d --buildThis will build the image and start the container.