How shamit-rath/grokart works
1. Overall shape
- grokart is a split frontend/backend grocery delivery platform.
- The client is a React single-page app built with Vite.
- The server is an Express API backed by MongoDB, with separate concerns for users, sellers, products, carts, orders, delivery, search, and recommendations.
2. Frontend boundary
- client/src/main.jsx and App.jsx are the application entry and top-level composition points.
- UI is organized into reusable components under components/ and route-level views under pages/.
- The frontend appears to be a consumer storefront plus a seller portal, both served from the same React app.
3. Client-side feature areas
- Storefront pages include home, all products, product details, category browsing, cart, address entry, and order history.
- Shared storefront components include navigation, banners, product cards, categories, newsletter, loading states, and recommendation/bestseller blocks.
- Seller functionality is separated under components/seller/ and pages/seller/, including seller login, product management, order handling, inventory alerts, and a seller layout shell.
4. Client state and data access
- context/AppContext.jsx is the main shared state boundary on the client.
- This likely centralizes app-wide data such as user/session state, cart state, product data, and API interactions.
- The client directory does not show a dedicated state library beyond React context, suggesting a relatively lightweight state architecture.
5. Backend API layer
- The server is organized around REST-style routes in server/routes/.
- Each route module maps to a domain controller in server/controllers/, keeping HTTP wiring separate from business logic.
- This separation is strong enough to diagram as: React UI → API routes → controllers → models/database.
6. Domain services on the server
- Core controllers exist for users, sellers, products, carts, orders, addresses, delivery, inventory alerts, search, and recommendations.
- This indicates the backend is not just CRUD; it also contains operational workflows like fulfillment and inventory monitoring.
- The presence of recommendation and search controllers suggests extra read-model or enrichment logic beyond basic product retrieval.
7. Data model boundary
- Persistence is modeled with MongoDB documents in server/models/.
- The main entities are User, Store, Product, Cart-related flows via controllers, Order, Address, InventoryAlert, and ProductInteraction.
- ProductInteraction is especially important because it supports recommendation or personalization behavior based on user activity.
8. Authentication and role separation
- There are distinct middleware modules for authUser and authSeller.
- This implies the platform has role-based access control with different protected API surfaces for customers and sellers.
- In diagrams, seller operations should be shown as a separate authenticated path from general customer operations.
9. Media and file handling
- server/configs/multer.js and server/configs/cloudinary.js show that product or asset uploads are handled through multipart upload middleware and cloud storage.
- This is likely used for product images and other seller-managed media.
- The architecture boundary is: upload request → middleware → cloud storage → persisted product record referencing the uploaded asset.
10. Infrastructure and runtime
- The server uses Express with MongoDB connection setup in server/configs/db.js.
- server/vercel.json and client/vercel.json indicate deployment targets are configured separately for frontend and backend.
- The repo also contains DB/debug scripts such as checkDB.js, checkMongoDB.js, checkStores.js, and debug_stores.js, which suggest operational validation around data integrity and environment connectivity.
11. Delivery and order flow
- Order placement and fulfillment are modeled as separate concerns rather than a single controller.
- orderController, deliveryController, and addressController imply a flow from cart to shipping address to order creation to delivery tracking/status.
- For an architecture diagram, these should be shown as sequential business steps with order state persisted in MongoDB.
12. Search and discovery flow
- searchController and frontend product/category pages form the discovery path.
- The storefront likely queries filtered product lists from the backend rather than doing client-side-only filtering.
- This matters because product discovery appears to be server-driven, not just rendered from static client data.
13. Recommendations and behavioral data
- recommendationController and ProductInteraction indicate a feedback loop based on user actions.
- The system likely records interactions, then uses them to generate personalized recommendations or related-product suggestions on the frontend.
- This is a distinct data pipeline from the core catalog and order pipeline.
14. Practical diagram takeaway
- The cleanest architecture view is:
- React storefront/seller UI
- Shared client context
- Express REST API
- Auth middleware split by role
- Domain controllers
- MongoDB models
- Cloudinary for uploaded media
- The two main vertical slices are customer shopping and seller operations, both backed by the same API and data store.
Main entry points: productRoute.js Routes · Product.js Mongo models · productController.js Catalog · orderController.js Orders
Components 19
Client
React storefront and seller portal
- App shell · Vite entry and top-level React composition
client/src/main.jsx - Storefront UI · Consumer pages and reusable storefront components
client/src/pages/Home.jsx - Seller portal · Seller-facing pages and login flow
client/src/pages/seller/SellerLayout.jsx - App context · Shared client state and API access boundary
client/src/context/AppContext.jsx
Server
Express API and data layer
- API server · HTTP server and route composition
server/server.js - Routes · Domain route modules mapping endpoints to controllers
server/routes/productRoute.js - Auth middleware · Separate customer and seller request protection
server/middlewares/authUser.js - User ops · Customer and account management logic
server/controllers/userController.js - Seller ops · Seller account and store management logic
server/controllers/sellerController.js - Catalog · Product browsing, listing, and product details
server/controllers/productController.js - Search · Product discovery and filtered lookup
server/controllers/searchController.js - Cart · Cart persistence and item updates
server/controllers/cartController.js - Orders · Order creation and order lifecycle management
server/controllers/orderController.js - Delivery · Fulfillment and delivery status handling
server/controllers/deliveryController.js - Inventory · Inventory alerts and stock monitoring
server/controllers/inventoryController.js - Recommendations · Personalized and related-product generation
server/controllers/recommendationController.js - Mongo models · Persistent domain documents for users, stores, products, orders, addresses, alerts, and interactions
server/models/Product.js
Infra
Runtime, storage, and uploads
- MongoDB · Primary document database
server/configs/db.js - Cloudinary uploads · Image and asset upload pipeline for seller-managed media
server/configs/cloudinary.js
Connections 31
- App shell → Storefront UI: renders · Top-level app composition mounts storefront views and seller portal
- App shell → App context: uses · Provides shared client state and API access
- Storefront UI → App context: reads · Storefront pages consume shared app state
- Seller portal → App context: reads · Seller pages consume shared app state
- Storefront UI → API server: calls · Customer browsing, cart, and order flows hit the API
- Seller portal → API server: calls · Seller workflows hit the API
- API server → Routes: mounts · Express server wires route modules
- Routes → Auth middleware: protects · Routes apply role-based request guards where needed
- Routes → User ops: dispatches · User endpoints map to user controller actions
- Routes → Seller ops: dispatches · Seller endpoints map to seller controller actions
- Routes → Catalog: dispatches · Product endpoints map to catalog controller actions
- Routes → Search: dispatches · Search endpoints map to discovery logic
- Routes → Cart: dispatches · Cart endpoints map to cart controller actions
- Routes → Orders: dispatches · Order endpoints map to order controller actions
- Routes → Delivery: dispatches · Delivery endpoints map to fulfillment logic
- Routes → Inventory: dispatches · Inventory endpoints map to alerting logic
- Routes → Recommendations: dispatches · Recommendation endpoints map to personalization logic
- User ops → Mongo models: persists · User-related logic reads and writes Mongo documents
- Seller ops → Mongo models: persists · Seller and store logic reads and writes Mongo documents
- Catalog → Mongo models: persists · Catalog data is stored in Mongo documents
- Cart → Mongo models: persists · Cart state is stored through document models
- Orders → Mongo models: persists · Orders and addresses are stored in Mongo documents
- Delivery → Mongo models: persists · Delivery state updates order documents
- Inventory → Mongo models: persists · Inventory alerts are recorded as documents
- Recommendations → Mongo models: uses · Product interaction data feeds recommendation logic
- Mongo models → MongoDB: stored in · Mongo models are backed by the database connection
- Seller ops → Cloudinary uploads: uploads · Seller-managed media flows through upload storage
- Catalog → Cloudinary uploads: references · Products reference uploaded assets
- Search → Catalog: queries · Discovery builds on catalog data
- Orders → Delivery: advances · Placed orders move into delivery handling
- Cart → Orders: converts · Checkout turns cart contents into orders