CartBuddy is a real-time, location-aware peer-to-peer group buying application that helps neighbors, roommates, and colleagues split grocery delivery fees, unlock bulk discounts, and reduce carbon footprints by combining shopping baskets from popular platforms like Zepto, Blinkit, Swiggy Instamart, and Costco.
Explore the live instance of the CartBuddy application:
- Live Demo: https://cartbuddy-web.vercel.app/
On-demand quick-commerce and grocery delivery services have revolutionized shopping, but they come with hidden costs: high delivery surcharges, surge fees during peak hours, single-use plastic packaging, and carbon emissions from separate delivery vehicles visiting the same residential complex. Furthermore, individual buyers often miss out on attractive "buy 1 get 1" or bulk pricing discount tiers because their cart sizes are too small.
CartBuddy coordinates local shopping demands by connecting nearby users in real time. It enables a "Host" to start a joint shopping cart for a specific platform and location. Neighbors within a set radial boundary see the group, join, chat, coordinate item additions, and split the final order delivery expenses.
- Apartment Residents / Neighbors looking to coordinate daily grocery and food ordering runs.
- University Dorm Students / Roommates seeking to bundle platform subscription benefits (e.g., free delivery tiers).
- Office Cohorts organizing shared lunch orders or coffee runs.
- Reduce Overhead Costs: Share platform fees, processing fees, and tip amounts.
- Eco-Friendly Handover: Replace five individual delivery scooter trips with a single bulk delivery.
- Establish Local Trust: Reward cooperative members using a peer-reviewed trust score system.
- Double-Token Auth: Custom JWT authentication implementation utilizing access tokens (15-min lifespan) paired with rotation-ready Refresh Tokens securely stored in MongoDB and distributed via
httpOnlycookies. - Verify-OTP Gate: New registrations require strict email verification via 6-digit OTP codes, handled asynchronously by
BullMQemail queues. - Route Guards: Protected frontend routing using React Router DOM wrapper components.
- Map Dashboard View: Visualizes nearby shopping carts on a dark-themed interactive map powered by the Leaflet engine.
- Geospatial Radial Search: MongoDB
$nearSpherequeries find active carts within a user-customizable radius (e.g. 500m, 1km). - Group Management: Hosts have full control to approve members, lock the cart once full, check out the order, or kick unresponsive participants.
- WebSocket Chatrooms: Active members chat within dedicated group channels powered by Socket.io.
- Live Location Tracking: Group members broadcast their real-time coordinates on the map during delivery handover.
- Status Indicators: Instant sync for presence states, dynamic member counts, typing indicators, and message read receipts.
- Reputation Logging: A background Cron engine recomputes users' trust scores daily, indexing reports, ratings, and no-shows.
- Modular Scoring: Support for rule-based rating deductions or mock machine-learning inference scoring models.
- Framework: React 19 (Functional components, custom Hooks)
- Styling: Tailwind CSS v4.0 (Custom design system, Rose Gold theme)
- State & Routing: React Router DOM v7, React Context API
- Animations: GSAP (GreenSock) for high-performance scroll effects, Framer Motion for micro-interactions
- Mapping: Leaflet (OpenStreetMap) with a styled dark-theme overlay
- Framework: Express.js 4 on Node.js (>=18)
- Database ODM: Mongoose 8
- Real-Time Communication: Socket.io v4
- Asynchronous Task Queue: BullMQ v5
- Task Scheduler: Node-Cron
- Core Storage: MongoDB (Atlas Cloud)
- Cache & Queue Store: Redis (Upstash / Redis Cloud)
- CDN Image Hosting: Cloudinary (user avatar image uploads)
- Email Delivery: Brevo API & Nodemailer (SMTP transport)
CartBuddy splits traffic between REST HTTP APIs (authentication, profile updates, and static group indexing) and a continuous WebSockets connection (for chat message queues, presence states, typing indicator pings, and coordinate sharing).
graph LR
User[React SPA Client] ==>|HTTP REST| Express[Express API Server]
User ==>|WebSocket Connection| Socket[Socket.io Server]
Express --> DB[(MongoDB Atlas)]
Socket --> EventBus[Node Event Bus]
EventBus --> RedisCache[(Redis Cache)]
EventBus --> EmailQ[BullMQ Email Queue]
EmailQ --> Mailer[Brevo/SMTP Service]
For an in-depth breakdown of network flows and security parameters, see the Architecture Documentation.
cartbuddy/
├── assets/ # Shared repository media (logos, banners, visual assets)
├── backend/ # Node.js Express Server
│ ├── src/
│ │ ├── api/v1/ # Versioned API layout (controllers, routes)
│ │ ├── config/ # Database, socket, redis, and env loading
│ │ ├── dtos/ # Data Transfer Objects for sanitized API outputs
│ │ ├── events/ # Local EventEmitter system
│ │ ├── jobs/ # Node-cron schedulers and background tasks
│ │ ├── middlewares/ # Authentication, rate limit, validation, sanitization
│ │ ├── models/ # MongoDB Mongoose collection schemas
│ │ ├── repositories/ # Data access layer isolation
│ │ ├── services/ # Core business logic handlers
│ │ ├── sockets/ # WebSocket handlers (chat, presence, tracking)
│ │ └── utils/ # Error classes, helpers
│ ├── .env.example
│ └── package.json
├── frontend/ # React Vite SPA Client
│ ├── public/ # Static assets (favicons, SVG layouts)
│ ├── src/
│ │ ├── assets/ # SVG, images imported by JSX components
│ │ ├── components/ # UI components (map, chat, rings, buttons)
│ │ ├── context/ # Auth, Socket, Notification Context Providers
│ │ ├── pages/ # Pages (Landing, Auth, Dashboard, Details, Profile)
│ │ ├── App.jsx # Route gates and structure
│ │ └── index.css # Global CSS variables & Tailwind directives
│ ├── .env.example
│ └── package.json
├── docs/ # Deep-dive system documentation
│ ├── architecture.md # Tech stack details and security processes
│ ├── api.md # Complete REST/WebSocket API endpoints guide
│ ├── database.md # Schemas, relations, and indexing details
│ ├── deployment.md # Step-by-step setup guides (Vercel, Render)
│ └── screenshots/ # Placeholders for portfolio screenshots
├── .editorconfig # Coding standards (tabs/spaces)
├── .gitattributes # Git line-endings standardization
└── .gitignore # Main repository git ignore configurations
- Node.js (v18 or higher)
- npm (v9 or higher)
- MongoDB running locally or a MongoDB Atlas account
- Redis running locally or an Upstash/Redis Cloud account
git clone https://github.com/codedbyanup/Cartbuddy.git
cd CartbuddyCopy the root .env.example configurations to .env files in both the frontend and backend folders:
# Backend Environment Setup
cp .env.example backend/.env
# Frontend Environment Setup
cp .env.example frontend/.envReview each .env file and input your local ports, MongoDB connections, JWT secret strings, and optional API keys (Redis, Cloudinary, SMTP).
In a new terminal window, navigate to the backend directory, install, and boot the server in development mode:
cd backend
npm install
npm run devThe server will boot by default on http://localhost:5000.
In a separate terminal window, navigate to the frontend directory, install, and boot the Vite server:
cd frontend
npm install
npm run devThe React app will launch on http://localhost:5173.
To generate a compiled and optimized static build of the frontend:
cd frontend
npm run buildA brief overview of key schemas and API endpoints is listed below. For full details, refer to:
CartBuddy operates with the following collections:
users: Stores emails, password hashes, current coordinates, profile images, and reputation metrics.groups: Contains active grocery carts, vendor platform types, host details, and order deadline times.groupmembers: Resolves user memberships, check-in states, and no-shows within shopping runs.messages: Chronological logs of group chat communications.otps: Expiring numeric codes used during registration and password resets.
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
POST |
/api/v1/auth/register |
Register new user account | No |
POST |
/api/v1/auth/login |
Login user, return JWT tokens | No |
GET |
/api/v1/users/me |
Fetch active profile information | Yes |
POST |
/api/v1/groups |
Create a new shared shopping group | Yes |
GET |
/api/v1/groups/nearby |
Query active groups within radius | Yes |
POST |
/api/v1/groups/:id/join |
Join an open group cart | Yes |
GET |
/api/v1/groups/:id/messages |
Load historical chat transcripts | Yes |
Add your own screenshots inside the docs/screenshots/ folder and update the links below to showcase the application to recruiters.
- Landing Page: Landing Page Preview
- Login / Register Portal: Auth Portal Preview
- Dashboard Map View: Dashboard Map Preview
- Group Details & Chat Room: Group Room Preview
- User Profile & Addresses: User Profile Preview
- AI-Powered Item Suggestions: Recommend items based on common store trends to group buyers.
- Receipt OCR Integration: Automatically read receipt images uploaded by the host and split bills to calculate individual member totals.
- Multi-platform Cart Sync: Sync items directly from Zepto/Blinkit cart sharing share links.
- Native Mobile Wrapper: Bundle the React app using Capacitor or Cordova for push notification support.
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project.
- Create your Feature Branch (
git checkout -b feature/AmazingFeature). - Commit your Changes (
git commit -m 'Add some AmazingFeature'). - Push to the Branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
Anup
- GitHub: @codedbyanup
- LinkedIn: LinkedIn Profile Placeholder
- Portfolio: Portfolio Website Placeholder
- Email: email-placeholder@domain.com