🚀 SmartAllocate — AI-Powered Volunteer Matching Platform

Match the Right Volunteers to the Right Tasks

SmartAllocate uses AI to intelligently match volunteers with NGO tasks based on skills, availability, and location — maximizing social impact while minimizing coordination overhead.

---

📋 Table of Contents

• About
• Features
• Tech Stack
• Project Structure
• Setup Guide
• AI Matching Logic
• API Endpoints
• Deployment

---

🎯 About

SmartAllocate is an AI-driven platform designed to solve inefficient volunteer allocation in NGOs by intelligently matching the right volunteers to the right tasks. It analyzes key factors such as:

• Skills — Jaccard similarity between volunteer skills and task requirements
• Availability — Schedule overlap matching
• Location — Haversine-based proximity scoring

The system reduces skill mismatches, balances workload, and improves coordination through real-time tracking, automated notifications, and impact analytics.

---

✨ Features

Feature	Description
🤖 AI Smart Matching	ML engine matches volunteers to tasks with 95% accuracy
👤 Volunteer System	Register, manage skills, set availability
🏢 NGO Dashboard	Post tasks, view matched volunteers, track performance
📊 Impact Analytics	Real-time charts tracking hours, tasks, and impact scores
🔔 Notifications	In-app alerts for matches, updates, and milestones
🔐 Google OAuth	Secure authentication via Firebase
📱 Responsive Design	Premium glassmorphism UI that works on all devices
⚡ Real-time Updates	Live availability tracking and instant notifications

---

🧠 Tech Stack

Frontend

• React 19 (with Vite)
• Tailwind CSS 4
• Framer Motion — Animations
• Recharts — Data visualization
• React Router — Navigation

Backend

• Node.js + Express.js
• MongoDB + Mongoose
• Firebase — Authentication

AI/ML Service

• Python + Flask
• scikit-learn — ML capabilities
• NumPy — Numerical computing

---

📁 Project Structure

SmartAllocate/
│
├── src/                    # Frontend (React + Vite)
│   ├── components/         # Reusable UI components
│   │   ├── Navbar.jsx
│   │   ├── Footer.jsx
│   │   ├── Sidebar.jsx
│   │   └── StatsCard.jsx
│   ├── pages/              # Page components
│   │   ├── LandingPage.jsx
│   │   ├── LoginPage.jsx
│   │   ├── Dashboard.jsx
│   │   ├── NGODashboard.jsx
│   │   └── ProfilePage.jsx
│   ├── hooks/              # Custom React hooks
│   ├── services/           # API service layer
│   └── App.jsx             # Main app with routing
│
├── backend/                # Backend (Node.js + Express)
│   ├── routes/             # API route definitions
│   ├── controllers/        # Request handlers
│   ├── models/             # MongoDB schemas
│   ├── middleware/          # Auth & rate limiting
│   └── server.js           # Express server entry
│
├── ml-service/             # ML Service (Python + Flask)
│   ├── model.py            # Matching algorithm
│   ├── train.py            # Training & evaluation
│   └── app.py              # Flask API
│
├── database/
│   └── schemas.md          # Database documentation
│
└── README.md

---

🛠 Setup Guide

Prerequisites

• Node.js 18+ — Download
• Python 3.9+ — Download
• MongoDB (optional) — Download or use MongoDB Atlas

Step 1: Clone & Install Frontend

cd SmartAllocate
npm install

Step 2: Start Frontend

npm run dev

Opens at http://localhost:5173

Step 3: Install & Start Backend

cd backend
npm install
npm run dev

Runs at http://localhost:5000

Step 4: Install & Start ML Service

cd ml-service
pip install -r requirements.txt
python app.py

Runs at http://localhost:5001

Step 5: Train the ML Model (Optional)

cd ml-service
python train.py

---

🤖 AI Matching Logic

The matching engine uses a weighted scoring system:

Factor	Weight	Method
Skill Match	50%	Jaccard Similarity between volunteer skills and task requirements
Availability	30%	Day overlap ratio between volunteer schedule and task days
Location	20%	Inverse Haversine distance (closer = higher score)

Formula

Total Score = (Skill Score × 0.5) + (Availability Score × 0.3) + (Location Score × 0.2)

Returns the top 3 best matches for any given task.

---

📡 API Endpoints

Volunteers

Method	Endpoint	Description
GET	/api/volunteers	List all volunteers
GET	/api/volunteers/:id	Get volunteer by ID
POST	/api/volunteers	Create volunteer
PUT	/api/volunteers/:id	Update volunteer

Tasks

Method	Endpoint	Description
GET	/api/tasks	List all tasks
POST	/api/tasks	Create task
PUT	/api/tasks/:id	Update task

AI Matching

Method	Endpoint	Description
POST	/api/matches/find	Find best matches for a task
GET	/api/matches/score/:vid/:tid	Score a volunteer-task pair
GET	/api/matches/stats	Get matching statistics

ML Service (Python)

Method	Endpoint	Description
POST	/match	Find top 3 matches
POST	/score	Score a specific pair
GET	/health	Health check
GET	/stats	Model configuration

---

🚀 Deployment

Frontend → Vercel

npm run build
# Deploy dist/ folder to Vercel

Backend → Render

# Push backend/ to a Git repo
# Connect to Render and set environment variables

ML Service → Google Cloud Run

# Containerize with Docker and deploy to Cloud Run

Database → MongoDB Atlas

• Create free cluster at mongodb.com/atlas
• Update MONGODB_URI in backend .env

---

📄 License

MIT License — Free for personal and commercial use.

---

Made with 💜 for Social Impact

SmartAllocate — Matching the right volunteers to the right tasks