Installation

This guide will help you set up CampusBite on your local machine for development purposes. The application consists of a React frontend, Node.js backend, and MongoDB database.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js >= 18.0.0 (Download)
npm >= 9.0.0 (comes with Node.js)
MongoDB >= 6.0 (Download)
Git for cloning the repository
Gmail account with App Password for email functionality (optional for development)

You can use a hosted MongoDB database like MongoDB Atlas (free tier available) instead of installing MongoDB locally.

Installation steps

Clone the repository

Clone the CampusBite repository to your local machine:

git clone https://github.com/your-org/campusbite.git
cd campusbite

Set up the database

Start MongoDB locally or create a cloud database:Option 1: Local MongoDB

# Start MongoDB service
# macOS (using Homebrew)
brew services start mongodb-community

# Linux
sudo systemctl start mongod

# Windows - MongoDB runs as a service after installation

Option 2: MongoDB Atlas (Cloud)

Create a free account at MongoDB Atlas
Create a new cluster (free tier available)
Create a database user and whitelist your IP
Get your connection string

MongoDB collections and indexes are automatically created on the first server start. You don’t need to run any migration scripts.

Your connection string should look like:

mongodb://localhost:27017/campusbite
# or for Atlas:
mongodb+srv://username:[email protected]/campusbite

Configure environment variables

The backend requires environment variables for database connection, JWT secrets, and email configuration.Create a .env file in the backend directory:

touch backend/.env

Add the following configuration (replace with your actual values):

backend/.env

# Server Configuration
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/campusbite
# or for MongoDB Atlas:
# MONGODB_URI=mongodb+srv://username:[email protected]/campusbite

# JWT Secrets (generate random strings)
JWT_SECRET=your-super-secret-jwt-key-min-32-chars
JWT_REFRESH_SECRET=your-super-secret-refresh-key-min-32-chars
JWT_EXPIRES_IN=1h
JWT_REFRESH_EXPIRES_IN=7d

# Email Configuration (Gmail SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASS=your-gmail-app-password
[email protected]

# Frontend URL
FRONTEND_URL=http://localhost:5173

Never commit your .env file to version control. It contains sensitive credentials.

Generate JWT secrets

Generate secure random strings for JWT_SECRET and JWT_REFRESH_SECRET:

# On Linux/macOS
openssl rand -base64 32

# On Windows (PowerShell)
-join ((65..90) + (97..122) + (48..57) | Get-Random -Count 32 | % {[char]$_})

Copy the generated strings into your .env file.

Set up Gmail App Password (optional)

For email verification and password reset functionality, you need a Gmail App Password:

Go to your Google Account
Navigate to Security > 2-Step Verification
Scroll down to App passwords
Select Mail and generate a new password
Copy the 16-character password and paste it as SMTP_PASS in your .env file

You can skip this step during development. Email sending will fail, but the application will still work for testing other features.

Configure frontend environment (optional)

The frontend uses Vite’s proxy configuration to forward API requests to the backend. No additional environment variables are required.If you need to customize the backend URL, create a .env file in the frontend directory:

frontend/.env

VITE_BACKEND_URL=http://localhost:5000

Install dependencies

Install dependencies for both frontend and backend:

npm run install:all

The backend uses these key dependencies:

backend/package.json

{
  "dependencies": {
    "express": "^5.2.1",
    "mongoose": "^8.12.1",
    "bcryptjs": "^3.0.3",
    "jsonwebtoken": "^9.0.3",
    "nodemailer": "^8.0.1",
    "cors": "^2.8.6",
    "helmet": "^8.1.0",
    "express-rate-limit": "^8.2.1",
    "multer": "^2.0.2",
    "zod": "^4.3.6"
  }
}

The frontend uses React 19 with Vite and Tailwind CSS v4:

frontend/package.json

{
  "dependencies": {
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "react-router-dom": "^7.13.0",
    "axios": "^1.13.5",
    "tailwindcss": "^4.1.18",
    "lucide-react": "^0.564.0",
    "sonner": "^2.0.7"
  }
}

Start the development servers

Open two terminal windows and start both servers:

cd backend
npm run dev

You should see output similar to:

Backend

[Startup] Database initialized successfully.
CampusBite server running on port 5000 in development mode

Frontend

  VITE v7.3.1  ready in 432 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Verify the installation

Open your browser and navigate to http://localhost:5173. You should see the CampusBite landing page.Test the API health endpoint:

curl http://localhost:5000/api/health

Expected response:

{
  "success": true,
  "message": "CampusBite API is running.",
  "timestamp": "2026-03-04T09:30:00.000Z"
}

Project structure

Understanding the project structure will help you navigate the codebase:

CampusBite/
├── backend/
│   ├── src/
│   │   ├── config/          # Database and email configuration
│   │   │   ├── db.js
│   │   │   ├── email.js
│   │   │   ├── preflight.js
│   │   │   └── uploads.js
│   │   ├── controllers/     # Route handlers for auth, orders, stores, etc.
│   │   │   ├── authController.js
│   │   │   ├── orderController.js
│   │   │   ├── storeController.js
│   │   │   └── ...
│   │   ├── middleware/      # Auth, validation, error handling
│   │   │   ├── authMiddleware.js
│   │   │   ├── errorHandler.js
│   │   │   └── ...
│   │   ├── models/          # MongoDB schemas
│   │   ├── routes/          # Express route definitions
│   │   │   ├── authRoutes.js
│   │   │   ├── orderRoutes.js
│   │   │   ├── storeRoutes.js
│   │   │   └── ...
│   │   ├── services/        # Email, OTP, payment services
│   │   ├── utils/           # Helper functions
│   │   └── index.js         # Application entry point
│   ├── .env                 # Environment variables (not in git)
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── ui/          # Reusable UI components
│   │   │   ├── layout/      # Navbar, Layout
│   │   │   └── shared/      # StatusBadge, OrderTimeline
│   │   ├── contexts/        # AuthContext, CartContext
│   │   ├── hooks/           # Custom React hooks
│   │   ├── lib/             # API client, validators
│   │   ├── pages/
│   │   │   ├── auth/        # Login, Register, Verify
│   │   │   ├── student/     # Stores, Menu, Cart, Orders
│   │   │   └── store/       # Dashboard, Orders, Menu
│   │   ├── App.jsx          # Route definitions
│   │   └── main.jsx         # Application entry point
│   ├── .env                 # Frontend environment variables (optional)
│   └── package.json
├── dev.js                   # Concurrent dev server script
├── package.json             # Root package with scripts
└── README.md

Available scripts

Run these commands from the root directory:

Script	Description
`npm run dev`	Start both frontend and backend concurrently
`npm run dev:backend`	Start backend server only
`npm run dev:frontend`	Start frontend dev server only
`npm run install:all`	Install dependencies for root, backend, and frontend

Backend scripts (run from backend/ directory):

Script	Description
`npm run dev`	Start backend with nodemon (auto-reload)
`npm start`	Start backend in production mode

Frontend scripts (run from frontend/ directory):

Script	Description
`npm run dev`	Start Vite dev server
`npm run build`	Build for production
`npm run preview`	Preview production build

Environment variables reference

Backend environment variables

Variable	Description	Required	Default
`PORT`	Backend server port	No	`5000`
`NODE_ENV`	Environment mode	No	`development`
`MONGODB_URI`	MongoDB connection string	Yes	-
`JWT_SECRET`	JWT signing secret (min 32 chars)	Yes	-
`JWT_REFRESH_SECRET`	Refresh token secret (min 32 chars)	Yes	-
`JWT_EXPIRES_IN`	Access token expiry time	No	`1h`
`JWT_REFRESH_EXPIRES_IN`	Refresh token expiry time	No	`7d`
`SMTP_HOST`	SMTP server hostname	No	`smtp.gmail.com`
`SMTP_PORT`	SMTP server port	No	`587`
`SMTP_USER`	SMTP email address	No	-
`SMTP_PASS`	SMTP password/app password	No	-
`FROM_EMAIL`	Sender email address	No	-
`FRONTEND_URL`	Frontend URL for email links	No	`http://localhost:5173`
`UPLOAD_DIR`	Directory for uploaded files	No	`backend/public/uploads`

Frontend environment variables

Variable	Description	Required	Default
`VITE_BACKEND_URL`	Backend API URL	No	`http://localhost:5000`

Vite automatically exposes environment variables prefixed with VITE_ to the client-side code.

Troubleshooting

Database connection fails

Error: Connection refused or Authentication failed Solution:

Ensure MongoDB is running:

# Check MongoDB status
# macOS
brew services list | grep mongodb

# Linux
sudo systemctl status mongod

# Windows - check Services app for MongoDB service

Verify your MONGODB_URI in .env:
- Check connection string format
- Ensure credentials are correct for Atlas
- For local: verify MongoDB is listening on port 27017

Test the connection manually:

# Using mongosh (MongoDB Shell)
mongosh "mongodb://localhost:27017/campusbite"

# For Atlas
mongosh "mongodb+srv://username:[email protected]/campusbite"

Verify your DATABASE_URL in .env:
- Check username, password, host, and database name
- Ensure the database exists: psql -l

Test the connection manually:

psql "postgresql://username:password@localhost:5432/campusbite"

Email not sending

Error: Invalid login or SMTP error Solution:

Enable 2-Step Verification on your Google account
Generate an App Password (not your regular Gmail password)
Verify SMTP_USER and SMTP_PASS in .env
Check that SMTP_PORT is 587 (not 465)

Frontend can’t reach backend

Error: Network Error or ERR_CONNECTION_REFUSED Solution:

Ensure backend is running on port 5000:
```
curl http://localhost:5000/api/health
```

Check Vite proxy configuration in frontend/vite.config.js:

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:5000',
        changeOrigin: true
      }
    }
  }
})

Clear browser cache and restart the frontend dev server

Port already in use

Error: EADDRINUSE: address already in use :::5000 Solution:

Find and kill the process using the port:

# macOS/Linux
lsof -ti:5000 | xargs kill -9

# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

Or change the port in backend/.env:
```
PORT=5001
```

JWT token errors

Error: jwt malformed or invalid signature Solution:

Ensure JWT_SECRET and JWT_REFRESH_SECRET are properly set in .env
Clear browser cookies and local storage
Log out and log back in to get a fresh token

Module not found errors

Error: Cannot find module 'express' or similar Solution:

Delete node_modules and reinstall:

# Backend
cd backend
rm -rf node_modules package-lock.json
npm install

# Frontend
cd frontend
rm -rf node_modules package-lock.json
npm install

Verify Node.js version:
```
node --version  # Should be >= 18.0.0
```

Next steps

Quickstart

Create an account and place your first order

API Reference

Explore all available API endpoints

Authentication

Learn about JWT authentication flow

Deployment

Deploy CampusBite to production

Get Started

User Guides

Features

Deployment

Architecture

Prerequisites

Installation steps

Project structure

Available scripts

Environment variables reference

Backend environment variables

Frontend environment variables

Troubleshooting

Database connection fails

Email not sending

Frontend can’t reach backend

Port already in use

JWT token errors

Module not found errors

Next steps

Quickstart

API Reference

Authentication

Deployment

Build docs developers (and LLMs) love

Get Started

User Guides

Features

Deployment

Architecture

​Prerequisites

​Installation steps

​Project structure

​Available scripts

​Environment variables reference

​Backend environment variables

​Frontend environment variables

​Troubleshooting

​Database connection fails

​Email not sending

​Frontend can’t reach backend

​Port already in use

​JWT token errors

​Module not found errors

​Next steps

Quickstart

API Reference

Authentication

Deployment

Build docs developers (and LLMs) love

Prerequisites

Installation steps

Project structure

Available scripts

Environment variables reference

Backend environment variables

Frontend environment variables

Troubleshooting

Database connection fails

Email not sending

Frontend can’t reach backend

Port already in use

JWT token errors

Module not found errors

Next steps