# venkat-rgb/globemart architecture

> Architecture diagram of the GitHub repository venkat-rgb/globemart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/venkat-rgb/globemart
- Repository: https://github.com/venkat-rgb/globemart

## Overview

1. **High-level shape**
   - This repo is a **three-process MERN application**: a **React/Vite client**, an **Express/MongoDB API server**, and a separate **Socket.io service** for low-latency chat. The README and tree show it is deployed as containerized services rather than a single monolith.

2. **Client-side boundary**
   - The `client/` app is the user-facing SPA. It is organized by **feature/domain components** (`Products`, `Cart`, `Order`, `Payment`, `Chat`, `NearbyStores`, `Wishlist`, `Profile`, `admin/*`) plus reusable UI primitives in `components/UI`.
   - Routing is split into **customer routes** and **admin routes** under `utils/routes`, with `ProtectedRoute` and `ProtectedAdminRoute` enforcing access boundaries.

3. **Frontend state and data access**
   - Global state is split between **Redux Toolkit slices** for local UI/session state (`auth`, `cart`, `coupon`, sidebar/modal state) and **RTK Query API slices** for server data (`products`, `orders`, `payments`, `messages`, `reviews`, `coupons`, `wishlist`, etc.).
   - This means most server interactions flow: **page/component → RTK Query → Express API → MongoDB / external service → normalized UI state**.

4. **Customer commerce flow**
   - The primary user path is browse/search products, inspect a product detail page, add to cart, apply coupons, choose shipping/payment, and place an order.
   - Product pages are decomposed into subcomponents for images, buttons, features, reviews, and related items, which suggests the detail view is a composition point fed by multiple backend resources.

5. **Admin console boundary**
   - Admin functionality is a separate UI surface under `client/src/components/admin` and `pages/Admin.jsx`.
   - It covers **dashboard analytics**, **product CRUD**, **order fulfillment**, **user management**, **coupon management**, **reviews moderation**, and **support chat**. The dashboard reads from stats/aggregation endpoints rather than raw entity lists only.

6. **Backend API structure**
   - The `server/` app is organized by domain controllers and routes: `auth`, `users`, `products`, `orders`, `payments`, `reviews`, `coupons`, `wishlist`, `addresses`, `nearbyStores`, `stats`, `chats/messages`, and `aiCustomerSupport`.
   - MongoDB models mirror those domains (`User`, `Product`, `Order`, `Review`, `Chat`, `Message`, `Store`, `Coupon`, `WishList`, `Address`, `Company`, `Conversation`), so the API is largely document-centric with separate collections per business capability.

7. **Security and request boundaries**
   - Authentication is **JWT-based** with middleware for token verification and token blacklisting, plus rate limiting on sensitive endpoints.
   - The server also uses standard hardening middleware and guards: centralized error handling, image size limits, and NoSQL injection protection. Role separation is important: **customer vs admin** is enforced on the server, not just in the client.

8. **Real-time chat subsystem**
   - Chat is not just REST-based; it is backed by a dedicated **Socket.io process** in `socket/` and client socket hooks in `client/src/hooks/socket`.
   - The data flow is event-driven: presence, typing, message delivery, seen status, unread counts, and support-agent chat UI all depend on socket events rather than polling. This is the main low-latency subsystem in the architecture.

9. **AI customer support and voice search**
   - The AI support system is a distinct backend capability using **LangChain/LangGraph** utilities under `server/utils/ai`.
   - It routes queries into intent-specific branches: general chat, policy FAQ retrieval, product information lookup, and review summarization. The knowledge sources are a mix of **MongoDB data** and **embedded documents** seeded by scripts, with embeddings generated via Gemini models.
   - Voice product search on the client feeds natural-language queries into this backend/search pipeline, turning spoken intent into product filters and search results.

10. **Nearby stores and geospatial lookup**
   - The “Nearby Stores” feature is a separate geospatial service path: the client uses map UI components (`Leaflet`-based) while the server uses MongoDB geospatial queries and distance calculations.
   - This is a fallback/discovery flow for out-of-stock products, linking product availability to offline store locations rather than treating inventory as purely digital.

11. **Payments, invoices, and order lifecycle**
   - Payment is split between **Stripe-backed online payment** and **cash on delivery** flows.
   - Order completion triggers downstream side effects: invoice generation, email notifications, and order status tracking. These side effects are part of the backend workflow, not the frontend.

12. **Scheduled background work**
   - Coupon activation/expiry is automated via a scheduled job in `server/utils/jobs/couponJob.js`, so coupon lifecycle is not driven by user actions.
   - The architecture therefore includes a small background-processing tier alongside request/response APIs.

13. **Deployment and runtime topology**
   - Each major runtime has its own Dockerfile: `client`, `server`, and `socket`, with `compose.yaml` coordinating them.
   - GitHub Actions detects changes in those folders, builds/pushes images, and deploys to a VPS behind **Nginx**. The deployment boundary is therefore containerized and service-oriented, with the reverse proxy fronting the public entrypoint.

14. **What to draw in an architecture diagram**
   - A useful diagram would show:
     - **Browser/client SPA**
     - **Express API service**
     - **Socket service**
     - **MongoDB**
     - External services: **Stripe**, **email provider**, **Cloudinary**, and **LLM/embedding providers**
     - A background job lane for coupon scheduling
   - The most important arrows are:
     - client → REST API for commerce/admin data
     - client ↔ socket service for live chat
     - server ↔ MongoDB for all core entities
     - server → external services for payments, media, email, and AI
     - scheduled jobs → MongoDB for coupon state changes

Main entry points: [`server/server.js`](https://github.com/venkat-rgb/globemart/blob/main/server/server.js) (Express API), [`server/controllers/chatsController.js`](https://github.com/venkat-rgb/globemart/blob/main/server/controllers/chatsController.js) (Support Controllers), [`client/src/main.jsx`](https://github.com/venkat-rgb/globemart/blob/main/client/src/main.jsx) (React SPA), [`client/src/pages/Home.jsx`](https://github.com/venkat-rgb/globemart/blob/main/client/src/pages/Home.jsx) (Commerce UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_spa["React SPA<br/>vite app<br/>[main.jsx]"]
  node_customer_ui["Commerce UI<br/>feature UI<br/>[Home.jsx]"]
  node_admin_ui["Admin Console<br/>feature UI<br/>[Admin.jsx]"]
  node_client_state[("Client State<br/>redux state<br/>[store.js]")]
  node_client_api["RTK Query<br/>api layer<br/>[ecommerceApi.js]"]
  node_routes["Route Guards<br/>routing<br/>[basicRoutes.jsx]"]
end

subgraph group_server["API server"]
  node_api["Express API<br/>backend app<br/>[server.js]"]
  node_auth_sec["Auth & Guardrails<br/>middleware<br/>[verifyToken.js]"]
  node_commerce_ctrl["Commerce Controllers<br/>domain controllers"]
  node_support_ctrl["Support Controllers<br/>domain controllers<br/>[chatsController.js]"]
  node_ai_agent{{"AI Agent<br/>langchain flow<br/>[agentGraph.js]"}}
  node_scheduler["Coupon Jobs<br/>background job<br/>[couponJob.js]"]
end

subgraph group_socket["Realtime service"]
  node_socket_srv["Socket.io Server<br/>realtime service<br/>[index.js]"]
end

subgraph group_external["External systems"]
  node_email["Email Service<br/>external service"]
  node_payments["Stripe<br/>payment gateway"]
  node_media["Cloud Media<br/>asset service"]
  node_llm["LLM Provider<br/>ai provider"]
end

node_browser(("Browser<br/>user client"))
node_db[("MongoDB<br/>document store")]

node_browser -->|"uses"| node_spa
node_spa -->|"navigates"| node_routes
node_routes -->|"mounts"| node_customer_ui
node_routes -->|"mounts"| node_admin_ui
node_customer_ui -->|"reads/writes"| node_client_state
node_customer_ui -->|"queries"| node_client_api
node_admin_ui -->|"queries"| node_client_api
node_client_api -->|"REST"| node_api
node_spa -->|"socket"| node_socket_srv
node_socket_srv -->|"stores"| node_db
node_api -->|"protects"| node_auth_sec
node_api -->|"handles"| node_commerce_ctrl
node_api -->|"handles"| node_support_ctrl
node_commerce_ctrl -->|"reads/writes"| node_db
node_support_ctrl -->|"reads/writes"| node_db
node_support_ctrl -->|"coordinates"| node_socket_srv
node_support_ctrl -->|"invokes"| node_ai_agent
node_ai_agent -->|"retrieves"| node_db
node_ai_agent -->|"calls"| node_llm
node_scheduler -->|"updates"| node_db
node_api -->|"sends"| node_email
node_api -->|"charges"| node_payments
node_api -->|"uploads"| node_media

click node_spa "https://github.com/venkat-rgb/globemart/blob/main/client/src/main.jsx"
click node_customer_ui "https://github.com/venkat-rgb/globemart/blob/main/client/src/pages/Home.jsx"
click node_admin_ui "https://github.com/venkat-rgb/globemart/blob/main/client/src/pages/Admin.jsx"
click node_client_state "https://github.com/venkat-rgb/globemart/blob/main/client/src/redux/store.js"
click node_client_api "https://github.com/venkat-rgb/globemart/blob/main/client/src/redux/services/ecommerceApi.js"
click node_routes "https://github.com/venkat-rgb/globemart/blob/main/client/src/utils/routes/basicRoutes.jsx"
click node_api "https://github.com/venkat-rgb/globemart/blob/main/server/server.js"
click node_auth_sec "https://github.com/venkat-rgb/globemart/blob/main/server/middlewares/verifyToken.js"
click node_commerce_ctrl "https://github.com/venkat-rgb/globemart/blob/main/server/controllers/productController.js"
click node_support_ctrl "https://github.com/venkat-rgb/globemart/blob/main/server/controllers/chatsController.js"
click node_ai_agent "https://github.com/venkat-rgb/globemart/blob/main/server/utils/ai/agentGraph.js"
click node_scheduler "https://github.com/venkat-rgb/globemart/blob/main/server/utils/jobs/couponJob.js"
click node_socket_srv "https://github.com/venkat-rgb/globemart/blob/main/socket/index.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_spa,node_customer_ui,node_admin_ui,node_client_state,node_client_api,node_routes toneBlue
class node_api,node_auth_sec,node_commerce_ctrl,node_support_ctrl,node_ai_agent,node_scheduler toneAmber
class node_socket_srv toneMint
class node_email,node_payments,node_media,node_llm toneRose
class node_browser,node_db toneNeutral
```

## Components

### Client app

React/Vite SPA for shoppers and admins

- [React SPA](https://github.com/venkat-rgb/globemart/blob/main/client/src/main.jsx): vite app · Main client application shell and page routing · `client/src/main.jsx`
- [Commerce UI](https://github.com/venkat-rgb/globemart/blob/main/client/src/pages/Home.jsx): feature UI · Browse products, cart, orders, payment, wishlist, profile, and search · `client/src/pages/Home.jsx`
- [Admin Console](https://github.com/venkat-rgb/globemart/blob/main/client/src/pages/Admin.jsx): feature UI · Dashboard and back-office workflows for products, orders, users, coupons, reviews, and chat · `client/src/pages/Admin.jsx`
- [Client State](https://github.com/venkat-rgb/globemart/blob/main/client/src/redux/store.js): redux state · Redux slices for auth, cart, coupons, UI state, and review modal · `client/src/redux/store.js`
- [RTK Query](https://github.com/venkat-rgb/globemart/blob/main/client/src/redux/services/ecommerceApi.js): api layer · Client-side data access layer for REST resources · `client/src/redux/services/ecommerceApi.js`
- [Route Guards](https://github.com/venkat-rgb/globemart/blob/main/client/src/utils/routes/basicRoutes.jsx): routing · Separates customer and admin routes with protected access · `client/src/utils/routes/basicRoutes.jsx`

### API server

Express/MongoDB backend for commerce, support, and admin workflows

- [Express API](https://github.com/venkat-rgb/globemart/blob/main/server/server.js): backend app · Primary REST service coordinating auth, commerce, admin, and support features · `server/server.js`
- [Auth & Guardrails](https://github.com/venkat-rgb/globemart/blob/main/server/middlewares/verifyToken.js): middleware · JWT verification, blacklist checks, rate limiting, and error handling · `server/middlewares/verifyToken.js`
- [Commerce Controllers](https://github.com/venkat-rgb/globemart/blob/main/server/controllers/productController.js): domain controllers · Products, orders, payments, coupons, wishlist, addresses, nearby stores, reviews, and stats · `server/controllers/productController.js`
- [Support Controllers](https://github.com/venkat-rgb/globemart/blob/main/server/controllers/chatsController.js): domain controllers · Chat, messages, admin users, and AI customer support · `server/controllers/chatsController.js`
- [AI Agent](https://github.com/venkat-rgb/globemart/blob/main/server/utils/ai/agentGraph.js): langchain flow · Intent routing and retrieval tools for support, policy, product info, and review summaries · `server/utils/ai/agentGraph.js`
- [Coupon Jobs](https://github.com/venkat-rgb/globemart/blob/main/server/utils/jobs/couponJob.js): background job · Scheduled coupon activation and expiry processing · `server/utils/jobs/couponJob.js`

### Realtime service

Dedicated Socket.io process for live chat

- [Socket.io Server](https://github.com/venkat-rgb/globemart/blob/main/socket/index.js): realtime service · Low-latency chat and presence service · `socket/index.js`

### External systems

Third-party services used by the application

- **Email Service**: external service · Transactional email for password, order, and invoice flows
- **Stripe**: payment gateway · Online payment processing for checkout
- **Cloud Media**: asset service · Image and media storage for product and profile assets
- **LLM Provider**: ai provider · Embedding and model backend used by AI support and search features

### Other components

- **Browser**: user client · Customer and admin entrypoint for the SPA
- **MongoDB**: document store · Primary persistence for users, products, orders, chats, messages, stores, coupons, and reviews

## Connections

- Browser → React SPA: uses · User opens the web app
- React SPA → Route Guards: navigates · Client routes users into customer or admin areas
- Route Guards → Commerce UI: mounts · Customer pages and feature components
- Route Guards → Admin Console: mounts · Admin pages and back-office components
- Commerce UI → Client State: reads/writes · Local session and UI state
- Commerce UI → RTK Query: queries · Fetches commerce data from the API
- Admin Console → RTK Query: queries · Fetches admin and aggregation data from the API
- RTK Query → Express API: REST · Primary request/response path
- React SPA → Socket.io Server: socket · Live chat and presence updates
- Socket.io Server → MongoDB: stores · Persists chat state and message data
- Express API → Auth & Guardrails: protects · Authenticates and hardens sensitive routes
- Express API → Commerce Controllers: handles · Commerce and catalog workflows
- Express API → Support Controllers: handles · Support, chat, and admin workflows
- Commerce Controllers → MongoDB: reads/writes · Core business entities
- Support Controllers → MongoDB: reads/writes · Support and messaging entities
- Support Controllers → Socket.io Server: coordinates · Chat delivery and presence synchronization
- Support Controllers → AI Agent: invokes · AI support and retrieval flows
- AI Agent → MongoDB: retrieves · Uses stored product, policy, and review data
- AI Agent → LLM Provider: calls · Generates embeddings and model responses
- Coupon Jobs → MongoDB: updates · Activates and expires coupons
- Express API → Email Service: sends · Transactional notifications and invoices
- Express API → Stripe: charges · Stripe-backed checkout path
- Express API → Cloud Media: uploads · Product and profile asset handling