🎯 GestureWeb - AI Center of Excellence Platform

A cutting-edge MERN stack web application featuring advanced gesture controls and an intuitive admin portal for managing AI research and projects.

Demo • Features • Installation • Documentation

---

📋 Table of Contents

• Overview
• Key Features
• Tech Stack
• Project Structure
• Installation
• Configuration
• Usage
• Gesture Controls
• API Documentation
• Deployment
• Troubleshooting
• Contributing
• License

---

🌟 Overview

GestureWeb is a next-generation web platform that revolutionizes user interaction through gesture controls. Built for the AI Center of Excellence, it showcases cutting-edge web technologies including MediaPipe for hand gesture recognition and Three.js for immersive 3D experiences.

Why GestureWeb?

• 🎮 Hands-Free Navigation: Navigate the entire website using intuitive hand gestures
• 🔐 Secure Admin Portal: Comprehensive dashboard for content management
• 🌐 Cloud-Ready: MongoDB Atlas integration for scalable data storage
• ⚡ Performance Optimized: Built with React best practices and optimized bundle sizes
• 🎨 Modern UI/UX: Glassmorphism design with smooth animations

---

🚀 Key Features

🎮 Advanced Gesture Recognition

• Rock-Stable Tracking: Relative-straightness engine that works regardless of hand position or angle
• Mutual Exclusivity: Smart logic prevents conflicting gesture detection
• Mirror Mode: Natural camera control (move left to go left)
• Auto-Focus: Automatic centering on gesture-selected cards
• Singleton Pattern: Prevents WASM runtime crashes with optimized MediaPipe instance

🔐 Secure Admin Portal

• JWT Authentication: Encrypted token-based session management
• Role-Based Access: Protected routes for admin-only content
• Real-Time Analytics: Monitor views, subscribers, and engagement
• Content Management: Full CRUD operations for projects and research
• User Management: Manage contacts and newsletter subscriptions

✨ Premium UI/UX

• Glassmorphism Design: Modern aesthetic with frosted glass effects
• 3D Interactive Elements: Immersive card carousels using Three.js
• Particle Background: Dynamic particle system with React Three Fiber
• Smooth Animations: 60fps transitions with Framer Motion
• Responsive Layout: Fully optimized for desktop, tablet, and mobile

📊 Analytics & Monitoring

• Project View Tracking: Monitor which projects get the most attention
• Subscriber Metrics: Track newsletter growth over time
• Contact Form Analytics: View and manage user inquiries
• Database Connection Status: Real-time MongoDB connection monitoring

---

🛠️ Tech Stack

Frontend

• React 18.x - UI library
• Framer Motion - Animation library
• Three.js - 3D graphics
• React Three Fiber - React renderer for Three.js
• MediaPipe - Hand gesture recognition
• Axios - HTTP client
• React Router - Navigation

Backend

• Node.js - Runtime environment
• Express - Web framework
• MongoDB - Database (Atlas Cloud)
• Mongoose - ODM for MongoDB
• JWT - Authentication
• Bcryptjs - Password hashing
• Express Validator - Input validation
• Helmet - Security middleware
• Express Rate Limit - API rate limiting
• Nodemailer - Email service

DevOps & Tools

• dotenv - Environment configuration
• Nodemon - Development server
• ESLint - Code linting
• Git - Version control

---

🏗️ Project Structure

GestureWeb/
│
├── backend/                      # Node.js/Express backend
│   ├── src/
│   │   ├── app.js               # Express app configuration
│   │   ├── config/
│   │   │   └── db.js            # MongoDB connection with status logging
│   │   ├── controllers/         # Business logic
│   │   │   ├── authController.js
│   │   │   ├── projectController.js
│   │   │   ├── researchController.js
│   │   │   ├── contactController.js
│   │   │   ├── newsletterController.js
│   │   │   └── healthController.js
│   │   ├── middleware/
│   │   │   └── authMiddleware.js # JWT verification
│   │   ├── models/              # Mongoose schemas
│   │   │   ├── User.js
│   │   │   ├── Project.js
│   │   │   ├── ProjectView.js
│   │   │   ├── Research.js
│   │   │   ├── Contact.js
│   │   │   └── Newsletter.js
│   │   ├── routes/              # API route definitions
│   │   │   ├── index.js
│   │   │   ├── authRoutes.js
│   │   │   ├── projectRoutes.js
│   │   │   ├── researchRoutes.js
│   │   │   ├── contactRoutes.js
│   │   │   ├── newsletterRoutes.js
│   │   │   └── healthRoutes.js
│   │   └── seed/                # Database seeding scripts
│   │       ├── seed.js
│   │       └── seedAdmin.js
│   ├── server.js                # Server entry point
│   ├── package.json
│   └── .env                     # Environment variables
│
├── frontend/                     # React frontend
│   ├── public/
│   │   └── index.html
│   ├── src/
│   │   ├── components/          # Reusable components
│   │   │   ├── GestureControl.js      # Main gesture engine
│   │   │   ├── GestureIndicator.js    # Visual gesture feedback
│   │   │   ├── GestureStatus.js       # Status display
│   │   │   ├── Scene3D.js             # Three.js scenes
│   │   │   ├── ParticlesBackground.js # Particle system
│   │   │   ├── Navigation.js          # Navigation bar
│   │   │   ├── Footer.js              # Footer component
│   │   │   ├── DetailModal.js         # Modal for details
│   │   │   ├── Pagination.js          # Pagination control
│   │   │   ├── ScrollAnimation.js     # Scroll effects
│   │   │   └── ProtectedRoute.js      # Auth route guard
│   │   ├── context/             # React Context
│   │   │   └── GestureContext.js      # Gesture state management
│   │   ├── pages/               # Page components
│   │   │   ├── Home.js
│   │   │   ├── Projects.js
│   │   │   ├── Research.js
│   │   │   ├── Contact.js
│   │   │   ├── AdminLogin.js
│   │   │   ├── AdminDashboard.js
│   │   │   ├── AdminProjects.js
│   │   │   ├── AdminResearch.js
│   │   │   ├── AdminContact.js
│   │   │   ├── AdminSubscribers.js
│   │   │   └── AdminManagement.js
│   │   ├── utils/
│   │   │   └── api.js           # Axios API service
│   │   ├── App.js               # Main app component
│   │   ├── App.css
│   │   ├── index.js             # Entry point
│   │   └── index.css
│   ├── build/                   # Production build
│   └── package.json
│
└── README.md                    # This file

---

💻 Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v16 or higher)
• npm or yarn
• MongoDB Atlas account (or local MongoDB)
• Git

Step 1: Clone the Repository

git clone https://github.com/yourusername/GestureWeb.git
cd GestureWeb

Step 2: Backend Setup

1. Navigate to the backend directory:

cd backend

2. Install dependencies:

npm install

3. Create a .env file in the backend directory:

PORT=5000
MONGODB_URI=mongodb+srv://your_username:your_password@cluster0.xxxxx.mongodb.net/?appName=Cluster0
NODE_ENV=development
JWT_SECRET=your_super_secret_jwt_key_change_this_in_production
JWT_EXPIRES_IN=90d

4. Seed the admin user:

node src/seed/seedAdmin.js

This creates a default admin account:

• Email: admin@aicoe.com
• Password: HelloWorld!

5. (Optional) Seed sample data:

npm run seed

6. Start the backend server:

# Development mode with auto-reload
npm run dev

# Production mode
npm start

The backend will run on http://localhost:5000

Step 3: Frontend Setup

1. Open a new terminal and navigate to the frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Start the development server:

npm start

The frontend will run on http://localhost:3000

Step 4: Build for Production

To create a production build of the frontend:

cd frontend
npm run build

This creates an optimized build in the build/ directory.

---

⚙️ Configuration

Environment Variables

Backend (.env)

Variable	Description	Example
PORT	Server port	5000
MONGODB_URI	MongoDB connection string	mongodb+srv://user:pass@cluster.net/db
NODE_ENV	Environment mode	development or production
JWT_SECRET	Secret key for JWT tokens	your_secret_key_12345
JWT_EXPIRES_IN	Token expiration time	90d

Frontend (Optional)

Create .env in the frontend directory if needed:

REACT_APP_API_URL=http://localhost:5000/api

MongoDB Atlas Setup

1. Create a free account at MongoDB Atlas
2. Create a new cluster
3. Add a database user
4. Whitelist your IP address (or use 0.0.0.0/0 for all IPs)
5. Get your connection string and add it to the backend .env file

---

📖 Usage

Starting the Application

1. Start Backend (Terminal 1):

cd backend
npm run dev

2. Start Frontend (Terminal 2):

cd frontend
npm start

3. Open your browser to http://localhost:3000

Accessing the Admin Portal

1. Navigate to /admin/login
2. Use the default credentials:
   • Email: admin@aicoe.com
   • Password: HelloWorld!
3. Change the password after first login for security

Enabling Gesture Controls

1. Click the "Enable Gestures" button on the homepage
2. Allow camera access when prompted
3. Use the gestures listed in the Gesture Controls section

---

🖐️ Gesture Controls

GestureWeb uses MediaPipe for real-time hand gesture recognition. The system is designed for reliability and natural interaction.

Available Gestures

Gesture	Hand Shape	Action	Use Case
👆 Point	Index finger extended, others closed	Toggle Selection Mode	Switch between page/card navigation
👍 Thumbs Up	Thumb up, fingers closed	Scroll Up	Scroll page content upward
👎 Thumbs Down	Thumb down, fingers closed	Scroll Down	Scroll page content downward
✌️ Peace/Victory	Index & middle extended	Go Home	Return to homepage
← → Swipe	Open hand moving left/right	Navigate	Browse pages or 3D cards
✊ Fist	All fingers closed (hold 2s)	Pause Gestures	Temporarily disable detection
🖐️ Open Palm	All fingers extended	Resume/Activate	Re-enable gesture detection

Gesture Detection Features

• Relative Scoring: Works at any hand angle or distance
• Mutual Exclusivity: Prevents conflicting gesture triggers
• Debouncing: Prevents rapid repeated triggers
• Visual Feedback: On-screen indicators show detected gestures
• Mirror Mode: Natural camera interaction (intuitive direction mapping)

Tips for Best Results

• Ensure good lighting
• Keep hand within camera frame
• Make clear, deliberate gestures
• Wait for visual confirmation before next gesture
• Position camera at comfortable eye level

---

📡 API Documentation

Base URL

http://localhost:5000/api

Authentication

Most admin endpoints require a JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Public Endpoints

Health Check

GET /api/health

Check if API is running.

Projects

GET /api/projects

Get all projects (with view tracking).

Response:

[
  {
    "_id": "...",
    "title": "AI Research Project",
    "description": "Description here",
    "technologies": ["Python", "TensorFlow"],
    "imageUrl": "https://...",
    "demoUrl": "https://...",
    "githubUrl": "https://...",
    "views": 42,
    "featured": true,
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
]

Research Areas

GET /api/research

Get all research areas.

Contact Form

POST /api/contact
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "message": "Hello!"
}

Newsletter Subscription

POST /api/newsletter
Content-Type: application/json

{
  "email": "user@example.com"
}

Protected Endpoints (Admin Only)

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@aicoe.com",
  "password": "HelloWorld!"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "...",
    "email": "admin@aicoe.com",
    "name": "Admin"
  }
}

Dashboard Stats

GET /api/stats
Authorization: Bearer <token>

Response:

{
  "totalProjects": 10,
  "totalViews": 1453,
  "totalSubscribers": 234,
  "totalContacts": 89,
  "recentProjects": [...],
  "recentContacts": [...]
}

Project Management

# Create Project
POST /api/projects
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "New Project",
  "description": "Project description",
  "technologies": ["React", "Node.js"],
  "imageUrl": "https://...",
  "featured": false
}

# Update Project
PUT /api/projects/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Title",
  ...
}

# Delete Project
DELETE /api/projects/:id
Authorization: Bearer <token>

Research Management

# Get All Research
GET /api/research/admin
Authorization: Bearer <token>

# Create Research Area
POST /api/research
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Machine Learning",
  "description": "ML research area",
  "icon": "🤖"
}

# Update Research
PUT /api/research/:id
Authorization: Bearer <token>

# Delete Research
DELETE /api/research/:id
Authorization: Bearer <token>

Contact & Newsletter Management

# Get Contacts
GET /api/contacts
Authorization: Bearer <token>

# Delete Contact
DELETE /api/contacts/:id
Authorization: Bearer <token>

# Get Subscribers
GET /api/subscribers
Authorization: Bearer <token>

# Delete Subscriber
DELETE /api/newsletter/:id
Authorization: Bearer <token>

---

🚀 Deployment

Backend Deployment (Heroku Example)

1. Install Heroku CLI and login:

heroku login

2. Create app and add MongoDB addon:

heroku create your-app-name
heroku addons:create mongolab:sandbox

3. Set environment variables:

heroku config:set JWT_SECRET=your_secret_key
heroku config:set NODE_ENV=production

4. Deploy:

git push heroku main

Frontend Deployment (Vercel Example)

1. Install Vercel CLI:

npm i -g vercel

2. Deploy:

cd frontend
vercel --prod

3. Set environment variable in Vercel dashboard:

REACT_APP_API_URL=https://your-backend.herokuapp.com/api

Alternative: Docker Deployment

# Backend Dockerfile
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 5000
CMD ["npm", "start"]

---

🔧 Troubleshooting

Common Issues

MongoDB Connection Failed

Problem: ❌ MongoDB connection error

Solutions:

• Verify MONGODB_URI in .env file
• Check if IP is whitelisted in MongoDB Atlas
• Ensure database user credentials are correct
• Check internet connection

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::5000

Solutions:

# Find and kill process using port 5000 (Windows)
netstat -ano | findstr :5000
taskkill /PID <PID> /F

# Or change port in .env
PORT=5001

Gesture Detection Not Working

Problem: Gestures not recognized

Solutions:

• Grant camera permissions in browser
• Ensure good lighting conditions
• Check browser console for MediaPipe errors
• Try in Chrome/Edge (best MediaPipe support)
• Reload page and re-enable gestures

Build Errors

Problem: npm run build fails

Solutions:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# Check for missing imports
npm run build 2>&1 | grep "not defined"

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Write clear commit messages
• Test changes thoroughly
• Update documentation as needed
• Add comments for complex logic

Code Style

• Use ES6+ features
• Follow React best practices
• Use meaningful variable names
• Keep functions small and focused
• Add JSDoc comments for functions

---

🙏 Acknowledgments

• MediaPipe - Hand gesture recognition
• Three.js - 3D graphics
• Framer Motion - Animations
• MongoDB Atlas - Database hosting
• React - UI framework

---

**Made with ❤️ **

⭐ Star this repo if you find it helpful!