SurplusFlow 🚀

An AI-powered platform to reduce food waste and feed communities in real time.

Every day, perfectly good food is wasted while people go hungry.
SurplusFlow bridges this gap by connecting restaurants with NGOs using intelligent logistics and real-time coordination.

🌐 Live Demo: https://surplus-flow.vercel.app

---

✨ Key Highlights

• 🤖 AI-powered decision system (Google Gemini)
• 📍 Real-time NGO matching
• 🔐 OTP-based secure pickup
• 📦 Smart multi-NGO distribution
• 📊 Live tracking and impact dashboard

---

🧩 Problem It Solves

• Good food gets wasted every day
• NGOs often don’t know where food is available in time
• Pickup coordination is difficult without a unified system

👉 SurplusFlow solves this with real-time posting, AI insights, smart matching, and secure delivery flow.

---

⚙️ How SurplusFlow Works

1. Restaurant posts surplus food
2. AI analyzes urgency and gives recommendations
3. Nearby NGOs receive real-time alerts
4. NGO accepts the request
5. Pickup is verified using OTP
6. Delivery and impact metrics are updated

---

🚀 Main Features

• Real-time food posting
• Location-based NGO matching
• AI logistics assistant (Gemini)
• OTP-based secure handover
• Live rescue tracking
• Impact dashboard (meals served, food saved, CO₂ reduction)

---

🛠️ Tech Stack

• Frontend: React + Vite + Tailwind CSS
• Backend: Node.js + Express
• Database: MongoDB
• Authentication: Firebase
• AI: Google Gemini API
• Maps: Google Maps API
• Realtime: Socket.IO + Firebase Cloud Messaging

---

📁 Project Structure

surplusFlow/
	client/    # React frontend
	server/    # Node.js/Express backend

## Prerequisites

- Node.js 18+
- npm
- MongoDB database (local or Atlas)
- Firebase project
- Gemini API key

## Installation

### 1) Clone and open project

```bash
git clone <your-repo-url>
cd surplusFlow

2) Install frontend dependencies

cd client
npm install

3) Install backend dependencies

cd ../server
npm install

Environment Variables

Create two files:

• server/.env
• client/.env

server/.env

# Core
NODE_ENV=development
PORT=5000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret

# CORS (comma-separated)
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:5174

# Firebase Admin (backend)
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_CLIENT_EMAIL=your_firebase_client_email
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

# AI and notifications
GEMINI_API_KEY=your_gemini_api_key
NEARBY_ALERT_RADIUS_KM=25
DEFAULT_RADIUS_KM=20
MAX_RADIUS_KM=100

# Optional email service
RESEND_API_KEY=your_resend_api_key
MAIL_FROM=SurplusFlow <onboarding@resend.dev>
FRONTEND_URL=http://localhost:5173

# Optional pagination tuning
DEFAULT_PAGE_SIZE=10
MAX_PAGE_SIZE=50

Note: Firebase can run in mock mode for local testing if Firebase Admin env values are missing.

client/.env

VITE_FIREBASE_API_KEY=your_value
VITE_FIREBASE_AUTH_DOMAIN=your_value
VITE_FIREBASE_PROJECT_ID=your_value
VITE_FIREBASE_STORAGE_BUCKET=your_value
VITE_FIREBASE_MESSAGING_SENDER_ID=your_value
VITE_FIREBASE_APP_ID=your_value
VITE_FIREBASE_MEASUREMENT_ID=your_value

Run the Project Locally

Open two terminals from project root.

Terminal 1: Start backend

cd server
npm run dev

Backend runs at: http://localhost:5000

Terminal 2: Start frontend

cd client
npm run dev

Frontend runs at: http://localhost:5173

Build for Production

Frontend build

cd client
npm run build

Backend start

cd server
npm start

API Health Check

After backend starts, test:

GET http://localhost:5000/health

Expected response includes:

• success: true
• environment name
• timestamp