🛒 Quick Cart

A full-stack, real-time grocery delivery platform

Shop groceries, pay online, and watch your order travel to your door — live on a map.

---

📑 Table of Contents

• Overview
• Highlights
• Feature Breakdown
• Architecture
• Tech Stack
• Data Models
• Project Structure
• Getting Started
• Environment Variables
• API Reference
• Available Scripts
• Deployment
• Roadmap
• License

---

📖 Overview

Quick Cart is a production-style, end-to-end grocery e-commerce application built around three cooperating portals:

Portal	Who it's for	What they do
🧑 Storefront	Customers	Browse, add to cart, pay, and track orders live
🛠️ Admin	Store owners	Manage products, inventory, orders & delivery fleet
🚴 Delivery	Delivery partners	Accept jobs, stream GPS, confirm handover via OTP

It ships with a typed REST API, a serverless Postgres database, background job automation, transactional email, and real-time delivery tracking on an interactive map.

---

⭐ Highlights

• 💬 Built-in assistant chatbot — a context-aware helper that knows the whole site, searches the live product catalog, and guides users to deals, orders, payments and delivery.
• ❤️ Wishlist & favorites — save products with a one-tap heart and revisit them from a dedicated wishlist page.
• ⭐ Ratings & reviews — customers can rate products and write reviews, with a live rating summary and breakdown.
• 🗺️ Real-time order tracking — the delivery partner's live GPS is streamed to the customer's map (Leaflet), with a status timeline and ETA.
• 🔐 OTP-secured handover — deliveries are completed only after the customer verifies a one-time code.
• 💳 Real payments — Stripe Checkout for card payments (with webhook confirmation) plus Cash on Delivery.
• 🧑‍✈️ Role-based access — three independent auth flows (customer, admin, delivery) with dedicated middleware.
• 🖼️ Cloud image pipeline — product images uploaded via Multer → Cloudinary.
• ⚙️ Event-driven automation — Inngest jobs fire low-stock email alerts and scheduled monthly-offer campaigns.
• 📧 Transactional email — order & inventory notifications via Nodemailer.
• ⚡ Modern stack — React 19, Vite 8, Tailwind v4, Express 5, Prisma 7, serverless Neon Postgres — fully typed end to end.

---

🧩 Feature Breakdown

🧑 Customer Storefront

• Product catalog with categories, search, and advanced filters
• ⚡ Flash deals section with discounted pricing
• Slide-in cart sidebar with persistent state (Context API)
• Multi-step checkout — address → payment → review
• Stripe card payments & Cash on Delivery
• Address book — multiple saved addresses with default selection & geolocation
• Order history and detailed order views
• 📍 Live tracking — real-time map, status timeline, delivery OTP
• ❤️ Wishlist — save favorites and manage them on a dedicated page
• ⭐ Ratings & reviews — read and write product reviews with a rating breakdown
• 💬 Assistant chatbot — ask about products, orders, payments & delivery
• JWT authentication with protected routes

🛠️ Admin Panel

• Dashboard with business stats (revenue, orders, sales)
• Product management — full CRUD with Cloudinary image uploads
• Order management — view every order and update its status
• Delivery fleet — create/update partners and assign them to orders

🚴 Delivery Partner Portal

• Dedicated login and delivery dashboard
• My Deliveries list with full order details
• Live GPS location streaming to the customer's tracking map
• Complete / cancel deliveries with OTP verification at handover

⚙️ Platform & Automation

• Inngest background jobs — low-stock email alerts & monthly-offer cron
• Nodemailer transactional email (SMTP)
• Stripe webhooks for reliable payment confirmation
• Role-based middleware — auth, admin, deliveryAuth

---

🏗️ Architecture

flowchart LR
    subgraph Client["🖥️ Frontend — React 19 + Vite"]
        SF["🧑 Storefront"]
        AD["🛠️ Admin Panel"]
        DP["🚴 Delivery Portal"]
    end

    subgraph Server["⚙️ Backend — Express 5 + TypeScript"]
        API["REST API + JWT Auth"]
        JOBS["Inngest Jobs / Cron"]
    end

    subgraph External["☁️ Services"]
        DB[("🐘 Neon Postgres")]
        STRIPE["💳 Stripe"]
        CLOUD["🖼️ Cloudinary"]
        MAIL["📧 SMTP / Nodemailer"]
    end

    SF & AD & DP -->|Axios / REST| API
    API -->|Prisma| DB
    API -->|Checkout + Webhooks| STRIPE
    API -->|Image upload| CLOUD
    JOBS -->|Alerts & offers| MAIL
    API --> JOBS
    DP -.->|Live GPS| API -.->|Live location| SF

Loading

---

🧰 Tech Stack

Frontend

Tool	Purpose
React 19 + Vite 8	UI framework & build tooling
TypeScript	End-to-end type safety
Tailwind CSS v4	Utility-first styling
React Router 7	Client-side routing
Axios	HTTP client
Leaflet + React Leaflet	Live delivery map
React Hot Toast	Toast notifications
Lucide / React Icons	Iconography

Backend

Tool	Purpose
Node.js + Express 5	REST API server
TypeScript + tsx	Runtime & type safety
Prisma 7	Type-safe ORM
Neon (serverless Postgres)	Database
Inngest	Background jobs & cron
Stripe	Payments & webhooks
Cloudinary + Multer	Image storage & uploads
JWT + bcrypt	Auth & password hashing
Nodemailer	Transactional email

---

🗄️ Data Models

Defined in backend/prisma/schema.prisma:

Model	Purpose	Notable fields
User	Customers & admins	email (unique), password (hashed), addresses, orders
Address	Saved delivery addresses	label, city, zip, isDefault, lat / lng
Product	Catalog items	price, originalPrice, stock, category, isOrganic, rating
Order	Customer orders	items (JSON), paymentMethod, status, statusHistory, deliveryOtp, liveLocation, isPaid
DeliveryPartner	Delivery agents	email (unique), vehicleType, isActive, orders

---

📁 Project Structure

Quick-Cart/
├── backend/
│   ├── config/           # prisma, cloudinary, nodemailer
│   ├── controllers/      # auth, product, order, address, admin, deliveryPartner, webhooks
│   ├── middlewares/      # auth, admin, deliveryAuth (role guards)
│   ├── routes/           # REST route definitions
│   ├── inngest/          # background jobs (low-stock alerts, monthly offers)
│   ├── prisma/           # schema.prisma
│   ├── generated/        # generated Prisma client
│   ├── seed.ts           # database seeding
│   └── server.ts         # app entry point
│
└── frontend/
    └── src/
        ├── pages/         # Home, Products, Checkout, MyOrders, OrderTracking, ...
        ├── components/    # admin/, delivery/, Checkout/, Home/, OrderTracking/, ...
        ├── context/       # AuthContext, CartContext
        ├── config/        # Axios API client
        └── assets/        # static data & images

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• A Neon (or any Postgres) database URL
• Accounts for Stripe, Cloudinary, and an SMTP provider (for full functionality)

1. Clone

git clone https://github.com/rajatnagda45/Quick-Cart.git
cd Quick-Cart

2. Backend

cd backend
npm install
# create backend/.env (see below), then:
npx prisma generate
npm run seed        # optional: seed sample data
npm run server      # → http://localhost:8000  (nodemon hot-reload)

3. Frontend

cd ../frontend
npm install
# create frontend/.env (see below), then:
npm run dev         # → http://localhost:5173

---

🔌 API Reference

Method	Endpoint	Access	Description
POST	/api/auth/register	Public	Register a new user
POST	/api/auth/login	Public	Login and receive a JWT
GET	/api/products	Public	List / search products
GET	/api/products/flash-deals	Public	List flash deals
GET	/api/products/:id	Public	Product details
POST · PUT · DELETE	/api/products	Admin	Product CRUD
POST	/api/upload	Admin	Upload product image (Cloudinary)
GET · POST	/api/addresses	Auth	Manage saved addresses
POST	/api/orders	Auth	Create an order
GET	/api/orders	Auth	Current user's orders
GET	/api/orders/:id/location	Auth	Live delivery location
GET	/api/orders/all	Admin	All orders
PUT	/api/orders/:id/status	Admin	Update order status
GET	/api/admin/stats	Admin	Business stats
POST · PUT	/api/admin/delivery-partners	Admin	Manage delivery partners
PUT	/api/admin/orders/:id/assign	Admin	Assign a delivery partner
POST	/api/delivery/login	Public	Delivery partner login
GET	/api/delivery/my-deliveries	Partner	Assigned deliveries
PUT	/api/delivery/my-deliveries/:id/location	Partner	Push live GPS location
PUT	/api/delivery/my-deliveries/:id/complete	Partner	Complete delivery (OTP)
POST	/api/stripe	Webhook	Stripe payment webhook
ALL	/api/inngest	System	Inngest background jobs

---

📜 Available Scripts

Backend

Script	Action
npm run server	Dev server with hot reload (nodemon)
npm start	Start server (tsx)
npm run build	Compile TypeScript
npm run seed	Seed the database

Frontend

Script	Action
npm run dev	Start Vite dev server
npm run build	Type-check & build for production
npm run preview	Preview the production build
npm run lint	Run ESLint

---

🌐 Deployment

Both apps include vercel.json and are Vercel-ready:

1. Deploy backend/ and frontend/ as separate Vercel projects.
2. Add the environment variables above in each project's settings.
3. Point the frontend's VITE_BASE_URL at the deployed API URL.
4. Register the Stripe webhook (/api/stripe) and the Inngest endpoint (/api/inngest).

---

🗺️ Roadmap

• Product reviews & ratings UI
• Wishlist & favorites
• In-app assistant chatbot
• Coupon / promo-code engine
• Push notifications for order updates
• Analytics dashboard with charts
• Re-order shortcuts

---

📄 License

Released under the MIT License — free to use, modify, and distribute.

---

Built with React, Express & Prisma

⭐ If you find this project useful, consider giving it a star!