How venkat-rgb/globemart works
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.js Express API · chatsController.js Support Controllers · main.jsx React SPA · Home.jsx Commerce UI
Components 19
Client app
React/Vite SPA for shoppers and admins
- React SPA · Main client application shell and page routing
client/src/main.jsx - Commerce UI · Browse products, cart, orders, payment, wishlist, profile, and search
client/src/pages/Home.jsx - Admin Console · Dashboard and back-office workflows for products, orders, users, coupons, reviews, and chat
client/src/pages/Admin.jsx - Client State · Redux slices for auth, cart, coupons, UI state, and review modal
client/src/redux/store.js - RTK Query · Client-side data access layer for REST resources
client/src/redux/services/ecommerceApi.js - Route Guards · 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 · Primary REST service coordinating auth, commerce, admin, and support features
server/server.js - Auth & Guardrails · JWT verification, blacklist checks, rate limiting, and error handling
server/middlewares/verifyToken.js - Commerce Controllers · Products, orders, payments, coupons, wishlist, addresses, nearby stores, reviews, and stats
server/controllers/productController.js - Support Controllers · Chat, messages, admin users, and AI customer support
server/controllers/chatsController.js - AI Agent · Intent routing and retrieval tools for support, policy, product info, and review summaries
server/utils/ai/agentGraph.js - Coupon Jobs · Scheduled coupon activation and expiry processing
server/utils/jobs/couponJob.js
Realtime service
Dedicated Socket.io process for live chat
- Socket.io Server · Low-latency chat and presence service
socket/index.js
External systems
Third-party services used by the application
- Email Service · Transactional email for password, order, and invoice flows
- Stripe · Online payment processing for checkout
- Cloud Media · Image and media storage for product and profile assets
- LLM Provider · Embedding and model backend used by AI support and search features
Other components
- Browser · Customer and admin entrypoint for the SPA
- MongoDB · Primary persistence for users, products, orders, chats, messages, stores, coupons, and reviews
Connections 23
- 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