# 🍱 FoodRescue — Food Waste Management Platform

A full-stack MERN application connecting food donors (hotels, restaurants, bakeries) with NGOs, shelters, and volunteers.

---

## 📁 Project Structure

```
FoodRescue/
├── backend/                  # Node + Express + MongoDB
│   ├── config/
│   │   ├── db.js             # MongoDB connection
│   │   └── cloudinary.js     # Cloudinary + Multer setup
│   ├── controllers/
│   │   ├── authController.js
│   │   ├── donationController.js
│   │   ├── ngoController.js
│   │   ├── volunteerController.js
│   │   ├── adminController.js
│   │   └── analyticsController.js
│   ├── middleware/
│   │   ├── authMiddleware.js  # JWT protect + authorize
│   │   └── errorMiddleware.js
│   ├── models/
│   │   ├── User.js
│   │   ├── Donation.js
│   │   └── EmergencyAlert.js
│   ├── routes/
│   │   ├── authRoutes.js
│   │   ├── donationRoutes.js
│   │   ├── ngoRoutes.js
│   │   ├── volunteerRoutes.js
│   │   ├── adminRoutes.js
│   │   └── analyticsRoutes.js
│   ├── utils/
│   │   └── generateToken.js
│   ├── .env.example
│   ├── package.json
│   └── server.js             # Entry point
│
└── frontend/                 # React + Vite + Tailwind CSS
    ├── src/
    │   ├── components/
    │   │   └── common/
    │   │       ├── DashboardLayout.jsx  # Sidebar + header
    │   │       ├── DonationCard.jsx
    │   │       ├── StatCard.jsx
    │   │       ├── Spinner.jsx
    │   │       └── EmptyState.jsx
    │   ├── context/
    │   │   ├── AuthContext.jsx   # Global auth state
    │   │   └── SocketContext.jsx # Socket.IO real-time
    │   ├── pages/
    │   │   ├── LandingPage.jsx
    │   │   ├── LoginPage.jsx
    │   │   ├── RegisterPage.jsx
    │   │   ├── donor/
    │   │   │   ├── DonorDashboard.jsx
    │   │   │   ├── CreateDonation.jsx
    │   │   │   ├── MyDonations.jsx
    │   │   │   └── DonorImpact.jsx
    │   │   ├── ngo/
    │   │   │   ├── NGODashboard.jsx
    │   │   │   ├── BrowseFood.jsx
    │   │   │   ├── EmergencyAlert.jsx
    │   │   │   └── MyClaims.jsx
    │   │   ├── volunteer/
    │   │   │   ├── VolunteerDashboard.jsx
    │   │   │   └── AvailablePickups.jsx
    │   │   └── admin/
    │   │       ├── AdminDashboard.jsx
    │   │       ├── ManageUsers.jsx
    │   │       └── ManageDonations.jsx
    │   ├── services/
    │   │   └── api.js         # Axios instance + all API calls
    │   ├── App.jsx            # Routes + role-based navigation
    │   ├── main.jsx
    │   └── index.css          # Tailwind + custom classes
    ├── index.html
    ├── vite.config.js         # Dev proxy to backend
    ├── tailwind.config.js
    └── package.json
```

---

## 🚀 Quick Start

### 1. Clone and Install

```bash
# Install root concurrently
npm install

# Install backend deps
cd backend && npm install

# Install frontend deps
cd ../frontend && npm install
```

### 2. Configure Environment

```bash
cd backend
cp .env.example .env
# Edit .env with your values:
# - MONGO_URI (MongoDB Atlas or local)
# - JWT_SECRET (any long random string)
# - CLOUDINARY_* (from cloudinary.com)
```

### 3. Run Dev Server

```bash
# From root — runs both backend (port 5000) and frontend (port 5173)
npm run dev
```

Frontend: http://localhost:5173  
Backend API: http://localhost:5000/api

---

## 🔑 Roles & Access

| Role      | Can Do |
|-----------|--------|
| **Donor**     | Upload food, view donations, track impact, earn badges |
| **NGO**       | Browse/claim food, send emergency alerts, manage claims |
| **Volunteer** | Accept pickups, complete deliveries, earn points |
| **Admin**     | Manage users, verify NGOs, view all analytics |

---

## 🌐 API Endpoints

### Auth
```
POST /api/auth/register
POST /api/auth/login
GET  /api/auth/me          (protected)
PUT  /api/auth/profile     (protected)
```

### Donations
```
GET  /api/donations                    (all available)
POST /api/donations                    (donor only)
GET  /api/donations/my-donations       (donor only)
GET  /api/donations/:id
PUT  /api/donations/:id/claim          (ngo only)
PUT  /api/donations/:id/status
```

### NGO
```
GET  /api/ngos/nearby
GET  /api/ngos/leaderboard
GET  /api/ngos/emergencies
POST /api/ngos/emergency               (ngo only)
GET  /api/ngos/my-claims               (ngo only)
```

### Volunteer
```
GET /api/volunteers/available-pickups  (volunteer only)
PUT /api/volunteers/accept/:id         (volunteer only)
GET /api/volunteers/my-deliveries      (volunteer only)
```

### Analytics
```
GET /api/analytics/summary
GET /api/analytics/my-impact           (donor only)
```

### Admin
```
GET /api/admin/users
PUT /api/admin/verify-ngo/:id
PUT /api/admin/toggle-user/:id
GET /api/admin/donations
```

---

## ⚡ Real-Time Events (Socket.IO)

| Event | Direction | Trigger |
|-------|-----------|---------|
| `new-donation` | Server → NGOs | New food listed |
| `emergency-alert` | Server → All donors | NGO emergency |
| `donation-claimed` | Server → Donor | NGO claimed food |
| `volunteer-assigned` | Server → NGO | Volunteer accepted pickup |

---

## 🛠 Tech Stack

| Layer | Tech |
|-------|------|
| Frontend | React 18, Vite, Tailwind CSS, Recharts |
| Backend | Node.js, Express.js |
| Database | MongoDB + Mongoose |
| Auth | JWT (jsonwebtoken + bcryptjs) |
| Real-time | Socket.IO |
| File Upload | Multer + Cloudinary |
| Routing | React Router v6 |

---

## 📦 Production Build

```bash
cd frontend && npm run build
# Outputs to frontend/dist/
# Serve via Express static or deploy to Vercel/Netlify
```

For backend, deploy to Railway, Render, or any Node hosting. Set all `.env` variables in the dashboard.
