"A community-driven food rescue platform where AI does the heavy lifting — snap a photo, and a meal reaches someone in need."

     

---

📋 Table of Contents

1. 🌿 What is ResQPlate?
2. 🖼️ UI Showcase
3. 📊 Platform at a Glance
4. ✨ Key Features
5. 🏗️ System Architecture
   • 5.1 🔷 Architecture Diagram
   • 5.2 🧠 AI Layer Deep-Dive
   • 5.3 🔄 Data Flow Diagram
6. 🛤️ User Journey
7. 🗺️ 3D System Map
8. 🛠️ Tech Stack
9. 📂 Project Structure
10. 📦 Getting Started
    • 10.1 🔧 Prerequisites
    • 10.2 ⬇️ Install
    • 10.3 🔑 Environment Variables
    • 10.4 🖥️ Run & Build
11. ⚡ Performance
12. 🗺️ Roadmap
13. 🤝 Contributing
14. ❓ FAQ
15. 📄 Changelog
16. 👤 Author
17. ⭐ Show Your Support

---

1. 🌿 What is ResQPlate?

ResQPlate is a community-driven, AI-powered food rescue platform that connects donors, recipients, and volunteers to eliminate food waste and fight hunger. Donors can snap a photo of surplus food and post it in under 60 seconds — Groq Vision automatically extracts food details, Gemini AI matches it to nearby recipients, and volunteers coordinate real-time pickups via interactive maps.

🎯 Mission: Bridge the gap between food surplus and food scarcity using AI, community, and data.

🔖	Version	📦 Highlight
🆕	v2.0	ResQ-Agent Dispatcher · Eco-Heatmaps · Impact Analytics · Leaderboard
🔄	v1.5	Live order tracking · Volunteer routing · Smart Alerts · ResQBot
🎉	v1.0	Post in 60s · Groq Vision · Gemini Matching · Appwrite backend

---

2. 🖼️ UI Showcase

🏠 Dashboard — Command Centre

⚡ Quick Action Cards animate with botanical growth UI · Impact stats update in real-time · Smart Alerts pulse for nearby donations

📸 Post in 60 Seconds — AI-Powered Donation Flow

🤖 Groq Vision reads the food photo instantly · Gemini auto-fills Title, Quantity, Expiry · Zero manual typing required

🗺️ Live Order Tracking — Real-Time Map

📍 Leaflet maps volunteer position in real-time · Route optimisation for fastest pickup · Status updates ping donor and recipient simultaneously

📊 Impact Analytics — Community Leaderboard

🌍 Carbon saved calculated per donation · Meals rescued counter · Eco-heatmaps show hunger vs. waste zones geospatially

🤖 ResQBot — Your Intelligent Agent

🧠 Instant Query Resolution via Groq · Real-time Logistics Tracking via Appwrite · Sub-200ms Inference powered by Groq LPU technology

🖥️ View	📱 Mobile	💻 Tablet	🖥️ Desktop
🏠 Dashboard	✅	✅	✅
📸 Post in 60s	✅	✅	✅
🗺️ Live Tracking	✅	✅	✅
📊 Analytics	✅	✅	✅
💬 ResQBot Chat	✅	✅	✅

---

3. 📊 Platform at a Glance

mindmap
  root((🌿 ResQPlate))
    🤖 AI Engine
      Groq Vision
      Gemini Matching
      ResQBot Chat
      ResQ-Agent Dispatcher
    🍽️ Donor Flow
      Post in 60s
      AI Form Fill
      Impact Tracking
    🙏 Recipient Flow
      Browse Donations
      Request Food
      Order Tracking
    🚴 Volunteer Flow
      Pickup Routes
      Live Map
      Delivery Confirm
    📊 Impact
      Analytics Dashboard
      Eco Leaderboard
      Carbon Saved

Loading

🔢 Metric	🎯 Value	📝 Notes
⚡ Post Time	< 60s	Photo → live listing via Groq Vision
🤖 AI Models	2	Groq Llama 3.2 Vision + Google Gemini
📄 App Pages	16+	Full platform — dashboard to leaderboard
🧩 Components	25+	Reusable atomic UI library
🪝 Custom Hooks	3	Tracking, Alerts, Volunteer pickups
🗺️ Map Features	3	Live tracking · Routing · Eco-Heatmaps

---

4. ✨ Key Features

📸	Post in 60 Seconds	Snap a food photo — Groq Vision + Gemini auto-extract title, quantity, expiry, and category. Zero typing.
🤖	Smart AI Matching	Gemini AI matches donations with nearby recipients based on location, dietary need, and urgency
💬	ResQBot Chatbot	Gemini-powered conversational assistant for platform navigation, donation tips, and impact queries
🧠	ResQ-Agent Dispatcher	Deterministic agentic workflow (Groq Llama 3.1) for automated pickup negotiation between volunteers and donors
🔥	Smart Eco-Heatmaps	Leaflet-powered geospatial visualisation showing hunger zones vs. food waste hotspots in your city
🗺️	Live Order Tracking	Real-time volunteer position on an interactive map — donor and recipient both see pickup progress
🚴	Volunteer Pickups	Route-optimised pickup scheduling with one-tap accept and delivery confirmation
📊	Impact Analytics	Personal + global dashboards — meals rescued, carbon saved, waste diverted, all charted over time
🏆	Community Leaderboard	Gamified ranking by donation impact — top donors and volunteers recognised in real-time
🌱	Botanical Growth UI	Quick Action Cards animate as botanical trees growing — each donation visually grows the community garden
🔔	Smart Alerts	Push notifications for nearby donation opportunities, expiring food, and pickup assignments
🔐	Secure Auth	Appwrite-powered user authentication, profile management, and protected routes

---

5. 🏗️ System Architecture

5.1 🔷 Architecture Diagram

flowchart TB
    subgraph Client["🌐 CLIENT LAYER — React 19 + Vite 7"]
        UI[⚛️ React Components]
        Router[🛣️ React Router DOM 7]
        State[🔄 Context API<br/>Auth + Cart]
        Motion[🎨 Framer Motion<br/>Animations]
    end

    subgraph AI["🤖 AI LAYER"]
        Groq[👁️ Groq Vision<br/>Image Analysis]
        Gemini[🧠 Gemini AI<br/>Smart Matching]
        ResQBot[💬 ResQBot<br/>Chat Assistant]
        Agent[🕵️ ResQ-Agent<br/>Dispatcher]
    end

    subgraph Services["⚙️ SERVICE LAYER"]
        Appwrite[🔐 Appwrite<br/>Auth · DB · Storage · Realtime]
        Axios[📡 Axios HTTP]
        Toast[🔔 Smart Alerts]
        Email[📧 EmailJS]
    end

    subgraph Maps["🗺️ MAPPING LAYER"]
        Leaflet[🗺️ Leaflet]
        ReactLeaflet[⚛️ React Leaflet]
        Heatmap[🔥 Eco Heatmaps]
    end

    subgraph Pages["📄 16+ PAGES"]
        P1[🏠 Dashboard]
        P2[📸 Post in 60s]
        P3[🍽️ Food Listing]
        P4[🗺️ Order Tracking]
        P5[📊 Analytics]
        P6[🏆 Leaderboard]
        P7[🚴 Volunteer Pickup]
    end

    UI --> Router --> Pages
    UI --> State
    UI --> Motion
    Pages --> AI
    Pages --> Services
    Pages --> Maps
    P2 --> Groq --> Gemini
    P3 --> Gemini
    P4 --> ReactLeaflet --> Leaflet
    P5 --> Heatmap

    classDef client fill:#0a2e0a,stroke:#16a34a,stroke-width:2px,color:#fff;
    classDef ai fill:#0a0a2e,stroke:#4285F4,stroke-width:2px,color:#fff;
    classDef svc fill:#2e0a0a,stroke:#FF3366,stroke-width:2px,color:#fff;
    classDef map fill:#0a1a2e,stroke:#199900,stroke-width:2px,color:#fff;
    classDef page fill:#1a1a0a,stroke:#84cc16,stroke-width:2px,color:#fff;

    class UI,Router,State,Motion,Pages,P1,P2,P3,P4,P5,P6,P7 client;
    class Groq,Gemini,ResQBot,Agent ai;
    class Appwrite,Axios,Toast,Email svc;
    class Leaflet,ReactLeaflet,Heatmap map;

Loading

5.2 🧠 AI Layer Deep-Dive

🤖 Model	🔧 Task	⚡ Trigger	🏆 Output
Groq Llama 3.2 Vision	Image analysis	Food photo uploaded	Title, quantity, expiry, category auto-filled
Google Gemini	Smart matching	Donation posted	Top-3 nearby recipient matches
Google Gemini	ResQBot chat	User question	Conversational platform guidance
Groq Llama 3.1	ResQ-Agent	Volunteer assigned	Pickup negotiation agentic workflow

5.3 🔄 Data Flow Diagram

flowchart LR
    subgraph Input["📥 INPUT"]
        A[📸 Photo Upload]
        B[📝 Manual Entry]
    end

    subgraph AI_Processing["🤖 AI PROCESSING"]
        C[👁️ Groq Vision<br/>Image Analysis]
        D[🧠 Gemini<br/>Smart Matching]
        E[💬 ResQBot<br/>AI Assistant]
    end

    subgraph Core["⚙️ CORE SERVICES"]
        F[🔐 Appwrite DB]
        G[🗺️ Leaflet Maps]
        H[🔔 Smart Alerts]
    end

    subgraph Output["📤 OUTPUT"]
        I[🌿 Donor Impact]
        J[🍽️ Recipient Fed]
        K[🚴 Volunteer Active]
    end

    A --> C --> D --> F
    B --> F
    E --> D
    F --> G --> K
    F --> H --> J
    F --> I

Loading

---

6. 🛤️ User Journey

sequenceDiagram
    autonumber
    actor Donor
    participant App as 🌿 ResQPlate
    participant AI  as 🤖 AI Engine
    participant DB  as 🔐 Appwrite
    participant Vol as 🚴 Volunteer
    participant Rec as 🍽️ Recipient

    Note over Donor,App: 📸 Phase 1 — Post in 60s
    Donor->>App: Snap food photo
    App->>AI: Analyze via Groq Vision
    AI-->>App: Auto-fill food details
    App->>DB: Post donation listing
    DB-->>App: ✅ Confirmed

    Note over App,Rec: 🤖 Phase 2 — AI Matching
    App->>AI: Find matches via Gemini
    AI-->>App: Top recipient matches
    App->>Rec: 🔔 Notify — food available

    Note over App,Vol: 🚴 Phase 3 — Volunteer Coordination
    App->>Vol: 🔔 Notify pickup opportunity
    Vol->>App: Accept pickup
    App->>Rec: Food is on the way!

    Note over Vol,Donor: 🌿 Phase 4 — Delivery & Impact
    Vol->>App: Confirm pickup
    App->>DB: Update status → in transit
    Vol->>App: Confirm delivery
    App->>DB: Mark complete
    App->>Donor: 🌿 Impact summary — tree grows!

Loading

---

7. 🗺️ 3D System Map

┌─────────────────────────────────────────────────────────────────────┐
│              🌐 FRONTEND LAYER  —  React 19 + Vite 7                │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │    Pages  •  Components  •  Hooks  •  Contexts  •  Layouts   │  │
│   └──────────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────────┐
│               🤖 AI LAYER  —  Groq + Gemini                         │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │  Vision Analysis  •  Smart Matching  •  Chatbot  •  Agent   │  │
│   └──────────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────────┐
│           🗺️ MAPPING LAYER  —  Leaflet + React Leaflet              │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │   Live Tracking  •  Route Optimisation  •  Eco-Heatmaps     │  │
│   └──────────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────────┐
│              🔐 BACKEND LAYER  —  Appwrite Cloud                    │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │  Auth  •  Database  •  Storage  •  Functions  •  Realtime   │  │
│   └──────────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
                    🌍 Community Impact
             (🍽️ Food Waste ↓  ·  😊 Hunger ↓)

🏗️ Layer	⚙️ Technologies	📝 Responsibility
🌐 Frontend	React 19 · Vite 7 · Tailwind 4 · Framer Motion	UI rendering, animations, routing, state
🤖 AI Engine	Groq SDK · Google Gemini	Image analysis, matching, chatbot, agent
🗺️ Maps	Leaflet · React Leaflet	Live tracking, route optimisation, heatmaps
🔐 Backend	Appwrite	Auth, database, file storage, realtime events

---

8. 🛠️ Tech Stack

⚛️ Frontend

🤖 AI & Intelligence

🔐 Backend & Services

⚙️ Capability	🔬 Implementation	🏆 Result
⚡ Post Speed	Groq Vision → Gemini pipeline	Food listed in under 60 seconds
🤖 AI Matching	Gemini location + need scoring	Right food to right person
🗺️ Live Tracking	React Leaflet + Appwrite Realtime	Volunteer position updates live
🎨 Animations	Framer Motion botanical variants	Engaging, purposeful micro-interactions
🔐 Auth	Appwrite Auth + ProtectedRoute	Secure access control across all pages
📊 Analytics	Client-side aggregation + charting	Personal + global impact dashboards

---

9. 📂 Project Structure

🌿 ResQPlate/frontend/
│
├── 🎬 src/animations/
│   └── variants.js                  # Framer Motion animation variants
│
├── 🧩 src/components/
│   ├── 💬 Chat/
│   │   └── ResQBot.jsx              # Gemini AI chatbot interface
│   ├── 📧 Contact/
│   │   └── Contact.jsx              # Contact form (EmailJS)
│   ├── 📊 Dashboard/
│   │   ├── ImpactCard.jsx           # Animated impact statistics card
│   │   └── QuickDonationModal.jsx   # One-tap quick donation modal
│   ├── 📄 About.jsx                 # Platform about page
│   ├── 🃏 FoodCard.jsx              # Food listing item card
│   ├── 🏠 Landing.jsx               # Public landing page
│   ├── 🏷️ Logo.jsx                  # Brand logo component
│   ├── 🗺️ MapView.jsx               # Leaflet interactive map wrapper
│   ├── 🔝 Navbar.jsx                # Responsive navigation bar
│   ├── 🎞️ PageTransition.jsx        # Framer Motion page transitions
│   ├── 🔒 ProtectedRoute.jsx        # Auth guard for private routes
│   └── ⚡ QuickActionCard.jsx        # Botanical growth animated cards
│
├── 🔄 src/context/
│   ├── AuthContext.jsx              # Appwrite auth state + helpers
│   └── CartContext.jsx              # Food cart state management
│
├── 🪝 src/hooks/
│   ├── useOrderTracking.js          # Real-time order status logic
│   ├── useSmartAlerts.js            # Push notification + alert polling
│   └── useVolunteerPickups.js       # Volunteer assignment + routing
│
├── 🖼️ src/layouts/
│   └── DashboardLayout.jsx          # Shared dashboard sidebar + header
│
├── 📄 src/pages/
│   ├── 🤖 AIMatching.jsx            # Gemini-powered match discovery
│   ├── 📊 Analytics.jsx             # Impact charts + eco-heatmaps
│   ├── 🛒 Cart.jsx                  # Food cart review
│   ├── 💳 Checkout.jsx              # Checkout + confirmation flow
│   ├── 🏠 DashboardHome.jsx         # Main dashboard entry
│   ├── 📸 DonateFood.jsx            # Manual food donation form
│   ├── 🍽️ FoodListing.jsx           # Browse all available donations
│   ├── 🌿 ImpactDelivered.jsx       # Post-delivery impact summary
│   ├── 🏆 Leaderboard.jsx           # Community ranking board
│   ├── 🔑 Login.jsx                 # Appwrite auth login
│   ├── 🗺️ OrderTracking.jsx         # Live map order tracker
│   ├── ⚡ PostIn60Seconds.jsx        # AI-powered 60s donation flow
│   ├── 👤 Profile.jsx               # User profile + history
│   ├── ⚙️ Settings.jsx              # Preferences + notifications
│   ├── 📝 Signup.jsx                # New user registration
│   ├── 🔔 SmartAlerts.jsx           # Donation opportunity alerts
│   └── 🚴 VolunteerPickup.jsx       # Volunteer pickup dashboard
│
├── ⚙️ src/services/
│   ├── aiService.js                 # Groq + Gemini API wrappers
│   ├── appwrite.js                  # Appwrite client configuration
│   ├── dataService.js               # Data fetching + caching helpers
│   └── impactService.js             # Carbon + meal impact calculations
│
├── 🗄️ src/data/
│   └── mockData.js                  # Dev-time seed data
│
├── 🏠 src/App.jsx                   # Root component + all routes
├── 🚀 src/main.jsx                  # Vite app entry point
└── 🎨 src/index.css                 # Global styles + Tailwind directives

---

10. 📦 Getting Started

10.1 🔧 Prerequisites

🛠️ Tool	📌 Version	🔗 Link
	≥ 18.x	nodejs.org
	≥ 8.x	Bundled with Node
🔐 Appwrite	Cloud or self-hosted	appwrite.io
🤖 Groq API Key	Free tier	console.groq.com
🧠 Gemini API Key	Free tier	aistudio.google.com

10.2 ⬇️ Install

📥 Step 1 — Clone

git clone https://github.com/salonyranjan/ResQpla8.git
cd ResQpla8/frontend

📦 Step 2 — Install dependencies

npm install

10.3 🔑 Environment Variables

🔐 Step 3 — Create frontend/.env

cp .env.example .env

# Appwrite Configuration
VITE_APPWRITE_ENDPOINT="https://fra.cloud.appwrite.io/v1"
VITE_APPWRITE_PROJECT_ID="your_project_id"
VITE_APPWRITE_PROJECT_NAME="ResQPlate"
VITE_APPWRITE_DATABASE_ID="your_database_id"
VITE_APPWRITE_PICKUPS_COLLECTION_ID="pickups"
VITE_APPWRITE_BUCKET_ID="your_bucket_id"

# AI Inference (Groq LPU)
# IMPORTANT: Do not share your real key in public repositories.
VITE_GROQ_API_KEY="gsk_your_secret_key_here"

# Email Notification Service (EmailJS)
VITE_EMAILJS_PUBLIC_KEY="your_public_key"
VITE_EMAILJS_SERVICE_ID="your_service_id"
VITE_EMAILJS_NEWSLETTER_TEMPLATE_ID="your_newsletter_template_id"
VITE_EMAILJS_CONTACT_TEMPLATE_ID="your_contact_template_id"

🔐 Security note: .env is git-ignored. Never commit real keys. A .env.example template is provided — copy it and fill in your values.

10.4 🖥️ Run & Build

📜 Script	💻 Command	📝 Purpose
🚀 Dev server	npm run dev	Start Vite HMR at http://localhost:5173
🏗️ Production build	npm run build	Optimised output in dist/
🔍 Preview build	npm run preview	Test production build locally
🧹 Lint	npm run lint	ESLint code quality check

---

11. ⚡ Performance

📊 Metric	🎯 Value	📝 Notes
⚡ Post in 60s	< 60s	Photo → live listing via Groq + Gemini
🤖 Groq Vision	~800ms	Image analysis + field extraction
🧠 Gemini Match	~600ms	Recipient matching query
🏗️ Vite Build	< 5s	Production bundle with tree-shaking
🗺️ Map Render	< 200ms	Leaflet tiles + marker placement
🎨 Animation FPS	60fps	Framer Motion hardware-accelerated
📦 Bundle	Minimised	Code splitting + lazy loading per route

---

12. 🗺️ Roadmap

Status	🚀 Feature	🎯 Priority
✅	Post in 60s — Groq Vision + Gemini auto-fill	🔴 Core
✅	Smart AI Matching — Gemini recipient discovery	🔴 Core
✅	Live Order Tracking — Leaflet maps	🔴 Core
✅	ResQBot — Gemini conversational assistant	🔴 Core
✅	ResQ-Agent Dispatcher — Llama 3.1 agentic workflow	🔴 Core
✅	Eco-Heatmaps — hunger vs. waste geospatial viz	🔴 Core
✅	Leaderboard + Impact Analytics	🔴 Core
🔄	Push Notifications — native browser alerts	🟡 High
🔄	Offline Mode — PWA + service worker caching	🟡 High
🔄	Multi-language i18n — regional language support	🟡 High
📅	Mobile App — React Native port	🟢 Planned
📅	NGO Dashboard — bulk donation management panel	🟢 Planned
📅	Carbon Credits — blockchain-verified impact tokens	🟢 Planned
💡	AR Food Scanner — camera overlay for food ID	🔵 Idea
💡	Voice Commands — donate by speaking	🔵 Idea

💬 Open a feature request →

---

13. 🤝 Contributing

All contributions to reduce food waste are warmly welcome! 🌿

# 1. Fork the repository on GitHub
# 2. Create your feature branch
git checkout -b feature/your-feature

# 3. Commit with conventional format
git commit -m "feat: add your feature"
# Prefixes: fix: | docs: | style: | refactor: | test: | chore:

# 4. Push & open a PR
git push origin feature/your-feature

Contribution Guidelines:

• Follow the existing ESLint config — run npm run lint before submitting
• Write meaningful, conventional commit messages
• Update relevant documentation if adding new features
• Test across mobile and desktop breakpoints

Priority areas:

🔥 Area	📝 What's Needed
🌐 i18n	Multi-language support with react-i18next
📱 PWA	Service worker + offline caching strategy
🧪 Tests	Vitest + React Testing Library component coverage
🎨 UI	New Tailwind component variants, dark mode

---

14. ❓ FAQ

🤖 How does Post in 60 Seconds actually work?

When you upload a food photo, it's sent to Groq's Llama 3.2 Vision API, which identifies the food type, quantity, and condition. That structured output is passed to Google Gemini, which writes a formatted listing title, selects the correct category, and estimates an expiry window. The entire round-trip takes under 2 seconds — you just review and tap Post.

🔐 Are my API keys safe in the browser?

This is a frontend-first project using VITE_ prefixed env vars, which means keys are bundled into the client. For production at scale, proxy all AI calls through a backend serverless function (Appwrite Functions or Vercel Edge Functions) so keys never ship to the browser. A backend proxy layer is on the roadmap.

🗺️ Does live tracking use real GPS?

Yes — the useOrderTracking hook uses the browser's navigator.geolocation API to get the volunteer's coordinates and updates them in Appwrite Realtime. The donor and recipient see the volunteer's position update live on the Leaflet map without polling.

🔌 Can I self-host Appwrite instead of using the cloud?

Absolutely. Update VITE_APPWRITE_ENDPOINT in .env to your self-hosted instance URL (e.g. https://appwrite.yourdomain.com/v1). All Appwrite SDK calls in src/services/appwrite.js will automatically point to your instance.

---

15. 📄 Changelog

Version	Highlights
🆕 v2.0.0	ResQ-Agent Dispatcher · Eco-Heatmaps · Analytics · Leaderboard · Botanical UI
v1.5.0	Live order tracking · Volunteer routing · Smart Alerts · ResQBot chatbot
v1.0.0	🎉 Initial release — Post in 60s · Groq Vision · Gemini Matching · Appwrite

---

16. 👤 Author

✦ Salony Ranjan 🤖 AI Engineer  ·  🧑‍💻 Full-Stack Dev  ·  🌿 Tech for Social Good "Using AI and community to turn food surplus into impact — one plate at a time."

---

17. ⭐ Show Your Support

If ResQPlate inspired you, taught you something new, or made you think about food waste differently — show it some love! 🌿

💡 Pro Tip: Go to GitHub repo Settings → Social Preview and upload the hero screenshot. When you share on LinkedIn, your beautiful Cyber-Green UI shows instead of a generic GitHub card — perfect for a social impact project.

     

Made with 🌿 by Salony Ranjan  ·  © 2026 ResQPlate · MIT