# shamit-rath/grokart architecture

> Architecture diagram of the GitHub repository shamit-rath/grokart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shamit-rath/grokart
- Repository: https://github.com/shamit-rath/grokart

## Overview

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: [`server/routes/productRoute.js`](https://github.com/shamit-rath/grokart/blob/main/server/routes/productRoute.js) (Routes), [`server/models/Product.js`](https://github.com/shamit-rath/grokart/blob/main/server/models/Product.js) (Mongo models), [`server/controllers/productController.js`](https://github.com/shamit-rath/grokart/blob/main/server/controllers/productController.js) (Catalog), [`server/controllers/orderController.js`](https://github.com/shamit-rath/grokart/blob/main/server/controllers/orderController.js) (Orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_entry["App shell<br/>React entry<br/>[main.jsx]"]
  node_client_ui["Storefront UI<br/>React views<br/>[Home.jsx]"]
  node_client_seller["Seller portal<br/>React seller UI<br/>[SellerLayout.jsx]"]
  node_client_context["App context<br/>React state<br/>[AppContext.jsx]"]
end

subgraph group_server["Server"]
  node_server_api["API server<br/>Express app<br/>[server.js]"]
  node_routes["Routes<br/>[productRoute.js]"]
  node_auth{{"Auth middleware<br/>RBAC middleware<br/>[authUser.js]"}}
  node_users["User ops<br/>user controller<br/>[userController.js]"]
  node_sellers["Seller ops<br/>seller controller"]
  node_catalog["Catalog<br/>product controller"]
  node_search["Search"]
  node_cart["Cart<br/>[cartController.js]"]
  node_orders["Orders<br/>order controller<br/>[orderController.js]"]
  node_delivery["Delivery"]
  node_inventory["Inventory"]
  node_recommendations["Recommendations<br/>recommendation controller"]
  node_models[("Mongo models<br/>Mongoose models<br/>[Product.js]")]
end

subgraph group_infra["Infra"]
  node_storage[("MongoDB<br/>database<br/>[db.js]")]
  node_uploads["Cloudinary uploads<br/>media storage<br/>[cloudinary.js]"]
end

node_client_entry -->|"renders"| node_client_ui
node_client_entry -->|"uses"| node_client_context
node_client_ui -->|"reads"| node_client_context
node_client_seller -->|"reads"| node_client_context
node_client_ui -->|"calls"| node_server_api
node_client_seller -->|"calls"| node_server_api
node_server_api -->|"mounts"| node_routes
node_routes -->|"protects"| node_auth
node_routes -->|"dispatches"| node_users
node_routes -->|"dispatches"| node_sellers
node_routes -->|"dispatches"| node_catalog
node_routes -->|"dispatches"| node_search
node_routes -->|"dispatches"| node_cart
node_routes -->|"dispatches"| node_orders
node_routes -->|"dispatches"| node_delivery
node_routes -->|"dispatches"| node_inventory
node_routes -->|"dispatches"| node_recommendations
node_users -->|"persists"| node_models
node_sellers -->|"persists"| node_models
node_catalog -->|"persists"| node_models
node_cart -->|"persists"| node_models
node_orders -->|"persists"| node_models
node_delivery -->|"persists"| node_models
node_inventory -->|"persists"| node_models
node_recommendations -->|"uses"| node_models
node_models -->|"stored in"| node_storage
node_sellers -->|"uploads"| node_uploads
node_catalog -->|"references"| node_uploads
node_search -->|"queries"| node_catalog
node_orders -->|"advances"| node_delivery
node_cart -->|"converts"| node_orders

click node_client_entry "https://github.com/shamit-rath/grokart/blob/main/client/src/main.jsx"
click node_client_ui "https://github.com/shamit-rath/grokart/blob/main/client/src/pages/Home.jsx"
click node_client_seller "https://github.com/shamit-rath/grokart/blob/main/client/src/pages/seller/SellerLayout.jsx"
click node_client_context "https://github.com/shamit-rath/grokart/blob/main/client/src/context/AppContext.jsx"
click node_server_api "https://github.com/shamit-rath/grokart/blob/main/server/server.js"
click node_routes "https://github.com/shamit-rath/grokart/blob/main/server/routes/productRoute.js"
click node_auth "https://github.com/shamit-rath/grokart/blob/main/server/middlewares/authUser.js"
click node_users "https://github.com/shamit-rath/grokart/blob/main/server/controllers/userController.js"
click node_sellers "https://github.com/shamit-rath/grokart/blob/main/server/controllers/sellerController.js"
click node_catalog "https://github.com/shamit-rath/grokart/blob/main/server/controllers/productController.js"
click node_search "https://github.com/shamit-rath/grokart/blob/main/server/controllers/searchController.js"
click node_cart "https://github.com/shamit-rath/grokart/blob/main/server/controllers/cartController.js"
click node_orders "https://github.com/shamit-rath/grokart/blob/main/server/controllers/orderController.js"
click node_delivery "https://github.com/shamit-rath/grokart/blob/main/server/controllers/deliveryController.js"
click node_inventory "https://github.com/shamit-rath/grokart/blob/main/server/controllers/inventoryController.js"
click node_recommendations "https://github.com/shamit-rath/grokart/blob/main/server/controllers/recommendationController.js"
click node_models "https://github.com/shamit-rath/grokart/blob/main/server/models/Product.js"
click node_storage "https://github.com/shamit-rath/grokart/blob/main/server/configs/db.js"
click node_uploads "https://github.com/shamit-rath/grokart/blob/main/server/configs/cloudinary.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_entry,node_client_ui,node_client_seller,node_client_context toneBlue
class node_server_api,node_routes,node_auth,node_users,node_sellers,node_catalog,node_search,node_cart,node_orders,node_delivery,node_inventory,node_recommendations,node_models toneAmber
class node_storage,node_uploads toneMint
```

## Components

### Client

React storefront and seller portal

- [App shell](https://github.com/shamit-rath/grokart/blob/main/client/src/main.jsx): React entry · Vite entry and top-level React composition · `client/src/main.jsx`
- [Storefront UI](https://github.com/shamit-rath/grokart/blob/main/client/src/pages/Home.jsx): React views · Consumer pages and reusable storefront components · `client/src/pages/Home.jsx`
- [Seller portal](https://github.com/shamit-rath/grokart/blob/main/client/src/pages/seller/SellerLayout.jsx): React seller UI · Seller-facing pages and login flow · `client/src/pages/seller/SellerLayout.jsx`
- [App context](https://github.com/shamit-rath/grokart/blob/main/client/src/context/AppContext.jsx): React state · Shared client state and API access boundary · `client/src/context/AppContext.jsx`

### Server

Express API and data layer

- [API server](https://github.com/shamit-rath/grokart/blob/main/server/server.js): Express app · HTTP server and route composition · `server/server.js`
- [Routes](https://github.com/shamit-rath/grokart/blob/main/server/routes/productRoute.js): REST routes · Domain route modules mapping endpoints to controllers · `server/routes/productRoute.js`
- [Auth middleware](https://github.com/shamit-rath/grokart/blob/main/server/middlewares/authUser.js): RBAC middleware · Separate customer and seller request protection · `server/middlewares/authUser.js`
- [User ops](https://github.com/shamit-rath/grokart/blob/main/server/controllers/userController.js): user controller · Customer and account management logic · `server/controllers/userController.js`
- [Seller ops](https://github.com/shamit-rath/grokart/blob/main/server/controllers/sellerController.js): seller controller · Seller account and store management logic · `server/controllers/sellerController.js`
- [Catalog](https://github.com/shamit-rath/grokart/blob/main/server/controllers/productController.js): product controller · Product browsing, listing, and product details · `server/controllers/productController.js`
- [Search](https://github.com/shamit-rath/grokart/blob/main/server/controllers/searchController.js): search controller · Product discovery and filtered lookup · `server/controllers/searchController.js`
- [Cart](https://github.com/shamit-rath/grokart/blob/main/server/controllers/cartController.js): cart controller · Cart persistence and item updates · `server/controllers/cartController.js`
- [Orders](https://github.com/shamit-rath/grokart/blob/main/server/controllers/orderController.js): order controller · Order creation and order lifecycle management · `server/controllers/orderController.js`
- [Delivery](https://github.com/shamit-rath/grokart/blob/main/server/controllers/deliveryController.js): delivery controller · Fulfillment and delivery status handling · `server/controllers/deliveryController.js`
- [Inventory](https://github.com/shamit-rath/grokart/blob/main/server/controllers/inventoryController.js): inventory controller · Inventory alerts and stock monitoring · `server/controllers/inventoryController.js`
- [Recommendations](https://github.com/shamit-rath/grokart/blob/main/server/controllers/recommendationController.js): recommendation controller · Personalized and related-product generation · `server/controllers/recommendationController.js`
- [Mongo models](https://github.com/shamit-rath/grokart/blob/main/server/models/Product.js): Mongoose models · Persistent domain documents for users, stores, products, orders, addresses, alerts, and interactions · `server/models/Product.js`

### Infra

Runtime, storage, and uploads

- [MongoDB](https://github.com/shamit-rath/grokart/blob/main/server/configs/db.js): database · Primary document database · `server/configs/db.js`
- [Cloudinary uploads](https://github.com/shamit-rath/grokart/blob/main/server/configs/cloudinary.js): media storage · Image and asset upload pipeline for seller-managed media · `server/configs/cloudinary.js`

## Connections

- 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
