Installation Guide

System Requirements

Development

Node.js 16.x or higher
npm 8.x or higher
MongoDB 5.x or higher
4GB RAM minimum
Modern browser (Chrome, Firefox, Safari)

Production

Node.js 18.x LTS recommended
MongoDB Atlas or self-hosted
SSL certificate (for WebRTC)
2GB RAM minimum per instance
Linux server recommended

Frontend Installation

1. Clone and Navigate

git clone https://github.com/your-username/meetmates.git
cd meetmates/frontend

2. Install Dependencies

The frontend uses React 19 with Vite as the build tool:

npm install

Key Dependencies:

[email protected] - UI framework
[email protected] - Build tool and dev server
[email protected] - Real-time communication
[email protected] - Styling
[email protected] - Icons
[email protected] - HTTP client

3. Configure Environment Variables

Create a .env file in the frontend directory:

frontend/.env

VITE_BACKEND_URL=http://localhost:3001
VITE_GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com

VITE_BACKEND_URL

string

required

The URL where your backend server is running. For local development, use http://localhost:3001. For production, use your deployed backend URL with HTTPS.

VITE_GOOGLE_CLIENT_ID

string

required

Your Google OAuth 2.0 Client ID from Google Cloud Console. This is used for college email authentication.

4. Socket.IO Configuration

The Socket.IO client is configured in frontend/src/Socket.jsx:

frontend/src/Socket.jsx

import { io } from "socket.io-client";

const socket = io(import.meta.env.VITE_BACKEND_URL, {
  autoConnect: false,
});

export default socket;

The socket connection is set to manual (autoConnect: false) to ensure proper authentication token handling before connecting.

5. Run Development Server

npm run dev

The application will be available at http://localhost:5173

6. Build for Production

npm run build

This creates an optimized production build in the dist directory.

npm run preview

Backend Installation

1. Navigate to Backend Directory

cd backend

2. Install Dependencies

npm install

Key Dependencies:

[email protected] - Web framework
[email protected] - WebSocket server
[email protected] - MongoDB ODM
[email protected] - JWT authentication
[email protected] - Google OAuth
[email protected] - Password hashing
[email protected] - Environment variables
[email protected] - Cross-origin resource sharing

3. Configure Environment Variables

Create a .env file in the backend directory:

backend/.env

MONGODB_URI=mongodb://localhost:27017/meetmates
JWT_SECRET=your-super-secret-jwt-key-minimum-32-characters
CORS_ORIGIN=http://localhost:5173,https://www.meetmates.space
PORT=3001
GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com

MONGODB_URI

string

required

MongoDB connection string. For local development: mongodb://localhost:27017/meetmatesFor MongoDB Atlas: mongodb+srv://username:[email protected]/meetmates

JWT_SECRET

string

required

Secret key for signing JWT tokens. Must be at least 32 characters. Generate using:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

CORS_ORIGIN

string

required

Comma-separated list of allowed origins for CORS. Include both development and production URLs.

PORT

number

default:"3001"

Port number for the backend server to listen on.

GOOGLE_CLIENT_ID

string

required

Your Google OAuth 2.0 Client ID for verifying Google authentication tokens on the backend.

4. Database Setup

The application uses MongoDB with the following schema:

backend/models/User.js

const userSchema = new mongoose.Schema({
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true,
    trim: true
  },
  password: {
    type: String,
    required: function() {
      return !this.isGoogleUser;
    },
    minlength: 6
  },
  name: {
    type: String,
    trim: true
  },
  googleId: {
    type: String,
    unique: true,
    sparse: true
  },
  isGoogleUser: {
    type: Boolean,
    default: false
  },
  profilePicture: {
    type: String
  },
  withVideo: {
    type: Boolean,
    default: true
  },
  isVerified: {
    type: Boolean,
    default: false
  },
  createdAt: {
    type: Date,
    default: Date.now
  }
});

Passwords are automatically hashed using bcrypt before saving. Never store plain text passwords.

5. Start the Server

npm start

You should see:

Server running on port 3001
MongoDB connected

6. Server Architecture

The backend server (backend/server.js) implements:

HTTP Routes
Socket.IO Events
Matching Logic

// Authentication routes
POST /api/auth/signup          // Email/password signup
POST /api/auth/login           // Email/password login
POST /api/auth/google-login    // Google OAuth login
POST /api/auth/image-login     // ID card verification

// Protected routes
GET  /api/profile              // Get user profile (requires JWT)
GET  /api/verify-token         // Verify JWT validity

// Client → Server events
socket.emit('findChat', email, withVideo)  // Request chat partner
socket.emit('sendMessage', message)         // Send text message
socket.emit('next')                         // Skip to next partner
socket.emit('ready-to-connect')            // Ready for WebRTC
socket.emit('webrtc-offer', offer)         // WebRTC offer
socket.emit('webrtc-answer', answer)       // WebRTC answer
socket.emit('ice-candidate', candidate)    // ICE candidate

// Server → Client events
socket.on('waiting')                        // Waiting for match
socket.on('chatStart', {withVideo, partnerId}) // Match found
socket.on('message', {sender, text})        // Receive message
socket.on('partnerLeft', {partnerId})       // Partner disconnected
socket.on('onlineUsers', count)             // Online user count
socket.on('create-offer')                   // Initiate WebRTC offer

The server implements intelligent user matching:

backend/server.js (excerpt)

function matchUsers() {
  // First, match users with same video preference
  matchUsersByVideoPreference();
  
  // Then match remaining users regardless of preference
  if (waitingUsers.length >= 2) {
    matchRemainingUsers();
  }
}

function matchUsersByVideoPreference() {
  const videoUsers = waitingUsers.filter(id => 
    videoEnabledUsers.has(id)
  );
  const textOnlyUsers = waitingUsers.filter(id => 
    !videoEnabledUsers.has(id)
  );
  
  // Match video users together
  while (videoUsers.length >= 2) {
    const user1 = videoUsers.shift();
    const user2 = videoUsers.shift();
    createChatPair(user1, user2, true);
  }
  
  // Match text-only users together
  while (textOnlyUsers.length >= 2) {
    const user1 = textOnlyUsers.shift();
    const user2 = textOnlyUsers.shift();
    createChatPair(user1, user2, false);
  }
}

Google OAuth Setup

Create Google Cloud Project

Go to Google Cloud Console
Click Select a project > New Project
Enter project name (e.g., “MeetMates”) and click Create

Enable Google+ API

Navigate to APIs & Services > Library
Search for “Google+ API”
Click Enable

Configure OAuth Consent Screen

Go to APIs & Services > OAuth consent screen
Select Internal if using Google Workspace, or External
Fill in required fields:
- App name: MeetMates
- User support email: [email protected]
- Developer contact: [email protected]
Click Save and Continue

Create OAuth 2.0 Credentials

Go to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Select Web application
Configure:
- Name: MeetMates Web Client
- Authorized JavaScript origins:
  - http://localhost:5173 (development)
  - https://yourdomain.com (production)
- Authorized redirect URIs: (leave empty for this implementation)
Click Create
Copy the Client ID

Restrict to College Domain (Optional)

For production, restrict OAuth to your college domain:

In OAuth consent screen, add your college domain
Or implement domain validation in your backend:

backend/routes/auth.js

// Validate college email domain
const allowedDomains = ['@college.edu', '@university.edu'];
const emailDomain = email.substring(email.indexOf('@'));

if (!allowedDomains.includes(emailDomain)) {
  return res.status(403).json({ 
    error: 'Only college email addresses are allowed' 
  });
}

MongoDB Setup

Local MongoDB
MongoDB Atlas

Install MongoDB

sudo apt-get update
sudo apt-get install -y mongodb
sudo systemctl start mongodb
sudo systemctl enable mongodb

Verify Installation

mongosh
# Should connect to: mongodb://127.0.0.1:27017

Create Database

use meetmates
db.createCollection('users')

Create Atlas Cluster

Go to MongoDB Atlas
Sign up or log in
Click Build a Database
Choose FREE tier (M0)
Select your cloud provider and region
Click Create Cluster

Configure Access

Database Access: Create a database user
- Username: meetmates_user
- Password: Generate a secure password
- Role: Read and write to any database
Network Access: Add IP address
- For development: Add your current IP
- For production: Add your server IP
- Or: Allow access from anywhere (0.0.0.0/0) - less secure

Get Connection String

Click Connect on your cluster
Choose Connect your application
Copy the connection string
Replace <password> with your database user password
Replace <dbname> with meetmates

MONGODB_URI=mongodb+srv://meetmates_user:<password>@cluster0.xxxxx.mongodb.net/meetmates?retryWrites=true&w=majority

Verification

Test Backend

# Check server health
curl http://localhost:3001

# Test Google login endpoint (should return error without valid token)
curl -X POST http://localhost:3001/api/auth/google-login \
  -H "Content-Type: application/json" \
  -d '{"credential":"invalid"}'

Test Frontend

Open browser to http://localhost:5173
Open browser console (F12)
Check for:
- No CORS errors
- Socket.IO connection logs
- Google OAuth button renders

Test Full Flow

Authentication

Click Google login button
Sign in with college email
Should redirect to start page

Socket Connection

Check backend logs for “New user connected”
Check frontend console for Socket.IO connection

Matching (requires 2 users)

Open second browser window (incognito)
Both users click “Start Chat”
Should match and connect

WebRTC Video

Grant camera/microphone permissions
Video streams should appear for both users

Troubleshooting

Port Already in Use

# Find process using port 3001
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or change port in backend/.env
PORT=3002

MongoDB Connection Failed

# Check if MongoDB is running
sudo systemctl status mongodb

# Check connection string format
# Local: mongodb://localhost:27017/meetmates
# Atlas: mongodb+srv://user:[email protected]/meetmates

# Test connection
mongosh "your-connection-string"

CORS Errors

Ensure CORS_ORIGIN in backend .env includes your frontend URL:

CORS_ORIGIN=http://localhost:5173,https://yourdomain.com

Check backend logs for “Blocked by CORS” messages.

Google OAuth Not Working

Verify VITE_GOOGLE_CLIENT_ID and GOOGLE_CLIENT_ID match
Check authorized JavaScript origins in Google Cloud Console
Ensure Google+ API is enabled
Check browser console for OAuth errors

WebRTC Connection Failed

Grant camera/microphone permissions
Use HTTPS in production (required for WebRTC)
Check firewall settings for UDP ports
Test with STUN/TURN servers if behind NAT

Socket.IO Not Connecting

// Enable debug mode in frontend
const socket = io(import.meta.env.VITE_BACKEND_URL, {
  autoConnect: false,
  debug: true
});

Check:

Backend server is running
VITE_BACKEND_URL is correct
No firewall blocking WebSocket connections

Production Deployment

Frontend

Recommended Platforms:

Vercel
Netlify
Cloudflare Pages

Build Command:

npm run build

Environment Variables:

VITE_BACKEND_URL
VITE_GOOGLE_CLIENT_ID

Backend

Recommended Platforms:

Railway
Render
DigitalOcean
AWS EC2

Start Command:

npm start

Environment Variables:

All variables from .env file

Production Checklist:

Use HTTPS for both frontend and backend
Set strong JWT_SECRET (32+ characters)
Configure MongoDB Atlas with IP whitelist
Restrict Google OAuth to college domain
Enable rate limiting on API endpoints
Set up monitoring and logging
Configure CORS with specific origins only
Use environment-specific OAuth credentials

Get Started

Features

Development

​System Requirements

Development

Production

​Frontend Installation

​1. Clone and Navigate

​2. Install Dependencies

​3. Configure Environment Variables

​4. Socket.IO Configuration

​5. Run Development Server

​6. Build for Production

​Backend Installation

​1. Navigate to Backend Directory

​2. Install Dependencies

​3. Configure Environment Variables

​4. Database Setup

​5. Start the Server

​6. Server Architecture

​Google OAuth Setup

​MongoDB Setup

​Install MongoDB

​Verify Installation

​Create Database

​Create Atlas Cluster

​Configure Access

​Get Connection String

​Verification

​Test Backend

​Test Frontend

​Test Full Flow

​Troubleshooting

​Production Deployment

Frontend

Backend

​Next Steps

API Reference

Environment Variables

Build docs developers (and LLMs) love

System Requirements

Frontend Installation

1. Clone and Navigate

2. Install Dependencies

3. Configure Environment Variables

4. Socket.IO Configuration

5. Run Development Server

6. Build for Production

Backend Installation

1. Navigate to Backend Directory

2. Install Dependencies

3. Configure Environment Variables

4. Database Setup

5. Start the Server

6. Server Architecture

Google OAuth Setup

MongoDB Setup

Install MongoDB

Verify Installation

Create Database

Create Atlas Cluster

Configure Access

Get Connection String

Verification

Test Backend

Test Frontend

Test Full Flow

Troubleshooting

Production Deployment

Next Steps