# tarekmonowar/e-commerce-backend architecture

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

- Interactive diagram: https://gitdiagram.com/tarekmonowar/e-commerce-backend
- Repository: https://github.com/tarekmonowar/e-commerce-backend

## Overview

1. **Repository shape**
   - This is a **TypeScript/Node.js Express backend** organized as a modular REST API.
   - `src/server.ts` is the entry point, `src/app.ts` builds the Express app, and `src/app/routes/index.ts` aggregates the feature routes under a versioned API path.

2. **High-level architecture**
   - The code follows a **feature-module pattern** rather than a single layered monolith.
   - Each domain folder under `src/app/modules/*` usually contains a **controller, service, model, route, validation, and interface** files, which makes the boundaries easy to diagram: HTTP in → controller → service → persistence/external systems.

3. **Core business domains**
   - The main business modules are **auth, user, products, order, payment, coupon, otp, support, stats, and AI**.
   - This matches the e-commerce behavior described in the README: registration/login, product browsing, orders, payments, admin operations, and support workflows.

4. **Persistence boundary**
   - The repository is clearly built around **MongoDB models** for the main entities such as users, products, orders, coupons, and stats.
   - Services encapsulate the database logic, while controllers stay thin and translate HTTP requests into service calls.

5. **Authentication and session flow**
   - Authentication is split across `auth`, `user`, and middleware.
   - It supports **JWT-based sessions**, likely with refresh-token handling, plus **Google OAuth via Passport** (`config/passport.ts`).
   - `checkAuth` middleware protects private routes, and the app appears to support role-based access for admin vs. regular users.

6. **Validation and error handling**
   - Request validation is centralized through `validateRequest`, with per-module validation definitions in files like `products.validation.ts`, `coupon.validation.ts`, and `support.validations.ts`.
   - Errors are normalized using `AppError`, then handled by `globalErrorHandler` and `notFound`, which gives the API a consistent failure boundary.

7. **Product/catalog flow**
   - The product module is the main catalog boundary: it handles CRUD, filtering, and admin management.
   - `queryBuilder.ts` suggests the API supports **filtering, sorting, and pagination** for list endpoints, which is important for drawing the catalog/data-access path.

8. **Order, payment, and stock coordination**
   - Orders and payments are separate modules, with payment integration centered around **Stripe** per the README.
   - `reduceStock.ts` indicates that successful order/payment flows also update inventory, so the order pipeline likely spans product stock, order persistence, and payment confirmation.

9. **Uploads and media**
   - `multer.config.ts` and `cloudinary.config.ts` show a media pipeline for file uploads and hosted asset storage.
   - In architecture terms, file upload is an external side-path from the API to Cloudinary, likely used by products or user/profile assets.

10. **OTP and email delivery**
   - The `otp` module plus `sendEmail.ts` and EJS templates under `utils/templates` indicate email-based workflows for **OTP, password reset, and newsletter-style messages**.
   - This is an asynchronous support boundary: API request → token/OTP generation → email dispatch → later verification.

11. **AI subsystem**
   - The `Ai` module is a distinct subsystem with `prompt`, `serve`, `vectorEmbedding`, and `ai.services.ts`.
   - `embeddedData/basic.txt` and `advancedData.txt` suggest the AI feature uses **pre-embedded local knowledge sources** rather than only live database content, with embeddings/storage managed separately from the main CRUD modules.

12. **Caching and runtime infrastructure**
   - Redis appears in the config layer (`redis.config.ts`, `uptash.redis.ts`) and there is a cache-related middleware, so the app likely uses Redis for session/state/caching or AI/vector support.
   - `vercel.json` indicates the backend is deployed to **Vercel**, so the diagram should include a deployment/runtime boundary from the Express app to the hosting platform.

13. **Cross-cutting utilities**
   - Shared helpers in `utils/` handle concerns like JWT creation, cookie setting, email sending, standardized API responses, async error wrapping, and token generation.
   - These utilities reduce duplication across modules and are the main shared “platform” layer beneath the feature folders.

Main entry points: [`src/app/routes/index.ts`](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/routes/index.ts) (API routes), [`src/app.ts`](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app.ts) (App), [`src/app/modules/auth/auth.route.ts`](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/auth/auth.route.ts) (Auth), [`src/app/modules/products/products.route.ts`](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/products/products.route.ts) (Products)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server(("Server<br/>entrypoint<br/>[server.ts]"))
  node_app["App<br/>[app.ts]"]
  node_api_routes["API routes<br/>router<br/>[index.ts]"]
end

subgraph group_platform["Platform"]
  node_check_auth["Auth guard<br/>middleware<br/>[checkAuth.ts]"]
  node_validate_request["Validate<br/>middleware<br/>[validateRequest.ts]"]
  node_errors["Errors<br/>middleware"]
  node_jwt_utils["JWT<br/>token utils<br/>[jwt.ts]"]
  node_query_builder["Query builder<br/>data utils<br/>[queryBuilder.ts]"]
  node_stock_utils["Stock update<br/>order utils<br/>[reduceStock.ts]"]
  node_email_utils["Email<br/>delivery utils<br/>[sendEmail.ts]"]
end

subgraph group_features["Features"]
  node_auth["Auth<br/>[auth.route.ts]"]
  node_user["User<br/>[user.route.ts]"]
  node_products["Products<br/>[products.route.ts]"]
  node_order["Order<br/>[order.route.ts]"]
  node_payment["Payment<br/>[payment.route.ts]"]
  node_coupon["Coupon<br/>[coupon.route.ts]"]
  node_otp["OTP<br/>[otp.route.ts]"]
  node_support["Support<br/>[support.route.ts]"]
  node_stats["Stats<br/>[stats.route.ts]"]
  node_ai["AI<br/>[ai.route.ts]"]
end

subgraph group_storage["Data & externals"]
  node_env_config["Env config<br/>[env.ts]"]
  node_passport_config["Passport<br/>auth config<br/>[passport.ts]"]
  node_redis_config[("Redis<br/>cache config<br/>[redis.config.ts]")]
  node_cloudinary_config[("Cloudinary<br/>media config")]
  node_vercel["Vercel<br/>deployment<br/>[vercel.json]"]
end

node_server -->|"boots"| node_app
node_app -->|"mounts"| node_api_routes
node_api_routes -->|"route"| node_auth
node_api_routes -->|"route"| node_user
node_api_routes -->|"route"| node_products
node_api_routes -->|"route"| node_order
node_api_routes -->|"route"| node_payment
node_api_routes -->|"route"| node_coupon
node_api_routes -->|"route"| node_otp
node_api_routes -->|"route"| node_support
node_api_routes -->|"route"| node_stats
node_api_routes -->|"route"| node_ai
node_auth -->|"tokens"| node_jwt_utils
node_auth -->|"oauth"| node_passport_config
node_auth -->|"notify"| node_email_utils
node_user -->|"protect"| node_check_auth
node_products -->|"validate"| node_validate_request
node_products -->|"list"| node_query_builder
node_order -->|"inventory"| node_stock_utils
node_otp -->|"deliver"| node_email_utils
node_support -->|"validate"| node_validate_request
node_errors -->|"handle"| node_api_routes
node_app -->|"config"| node_env_config
node_app -->|"cache"| node_redis_config
node_app -->|"media"| node_cloudinary_config
node_app -.->|"deploys"| node_vercel

click node_server "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/server.ts"
click node_app "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app.ts"
click node_api_routes "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/routes/index.ts"
click node_auth "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/auth/auth.route.ts"
click node_user "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/user/user.route.ts"
click node_products "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/products/products.route.ts"
click node_order "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/order/order.route.ts"
click node_payment "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/payment/payment.route.ts"
click node_coupon "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/coupon/coupon.route.ts"
click node_otp "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/otp/otp.route.ts"
click node_support "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/support/support.route.ts"
click node_stats "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/stats/stats.route.ts"
click node_ai "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/Ai/ai.route.ts"
click node_check_auth "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/middleware/checkAuth.ts"
click node_validate_request "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/middleware/validateRequest.ts"
click node_errors "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/middleware/globalErrorHandler.ts"
click node_env_config "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/config/env.ts"
click node_passport_config "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/config/passport.ts"
click node_redis_config "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/config/redis.config.ts"
click node_cloudinary_config "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/config/cloudinary.config.ts"
click node_jwt_utils "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/utils/jwt.ts"
click node_query_builder "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/utils/queryBuilder.ts"
click node_stock_utils "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/utils/reduceStock.ts"
click node_email_utils "https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/utils/sendEmail.ts"
click node_vercel "https://github.com/tarekmonowar/e-commerce-backend/blob/main/vercel.json"

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_server,node_app,node_api_routes toneBlue
class node_check_auth,node_validate_request,node_errors,node_jwt_utils,node_query_builder,node_stock_utils,node_email_utils toneAmber
class node_auth,node_user,node_products,node_order,node_payment,node_coupon,node_otp,node_support,node_stats,node_ai toneMint
class node_env_config,node_passport_config,node_redis_config,node_cloudinary_config,node_vercel toneRose
```

## Components

### Runtime

Express app bootstrap and API assembly

- [Server](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/server.ts): entrypoint · Starts the Node.js process · `src/server.ts`
- [App](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app.ts): express app · Builds the Express application · `src/app.ts`
- [API routes](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/routes/index.ts): router · Mounts versioned feature routes · `src/app/routes/index.ts`

### Platform

Cross-cutting middleware, config, and shared utilities

- [Auth guard](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/middleware/checkAuth.ts): middleware · Protects private routes · `src/app/middleware/checkAuth.ts`
- [Validate](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/middleware/validateRequest.ts): middleware · Validates request payloads · `src/app/middleware/validateRequest.ts`
- [Errors](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/middleware/globalErrorHandler.ts): middleware · Normalizes API failures · `src/app/middleware/globalErrorHandler.ts`
- [JWT](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/utils/jwt.ts): token utils · Access and refresh token helpers · `src/app/utils/jwt.ts`
- [Query builder](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/utils/queryBuilder.ts): data utils · Filtering, sorting, pagination · `src/app/utils/queryBuilder.ts`
- [Stock update](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/utils/reduceStock.ts): order utils · Inventory reduction helper · `src/app/utils/reduceStock.ts`
- [Email](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/utils/sendEmail.ts): delivery utils · Template-based email sending · `src/app/utils/sendEmail.ts`

### Features

Business modules and domain flows

- [Auth](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/auth/auth.route.ts): module · Login, session, and OAuth flows · `src/app/modules/auth/auth.route.ts`
- [User](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/user/user.route.ts): module · Profile and account management · `src/app/modules/user/user.route.ts`
- [Products](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/products/products.route.ts): module · Catalog CRUD and filtering · `src/app/modules/products/products.route.ts`
- [Order](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/order/order.route.ts): module · Cart-to-order workflow · `src/app/modules/order/order.route.ts`
- [Payment](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/payment/payment.route.ts): module · Checkout and payment integration · `src/app/modules/payment/payment.route.ts`
- [Coupon](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/coupon/coupon.route.ts): module · Discount rules and validation · `src/app/modules/coupon/coupon.route.ts`
- [OTP](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/otp/otp.route.ts): module · One-time password flows · `src/app/modules/otp/otp.route.ts`
- [Support](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/support/support.route.ts): module · Help and contact workflows · `src/app/modules/support/support.route.ts`
- [Stats](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/stats/stats.route.ts): module · Reporting and analytics · `src/app/modules/stats/stats.route.ts`
- [AI](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/modules/Ai/ai.route.ts): module · Prompting and embedded knowledge · `src/app/modules/Ai/ai.route.ts`

### Data & externals

Persistence, media, messaging, and hosting boundaries

- [Env config](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/config/env.ts): config · Loads runtime settings · `src/app/config/env.ts`
- [Passport](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/config/passport.ts): auth config · Google OAuth strategy setup · `src/app/config/passport.ts`
- [Redis](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/config/redis.config.ts): cache config · Cache and session backing store · `src/app/config/redis.config.ts`
- [Cloudinary](https://github.com/tarekmonowar/e-commerce-backend/blob/main/src/app/config/cloudinary.config.ts): media config · Hosted asset storage · `src/app/config/cloudinary.config.ts`
- [Vercel](https://github.com/tarekmonowar/e-commerce-backend/blob/main/vercel.json): deployment · Serverless hosting boundary · `vercel.json`

## Connections

- Server → App: boots · Process entry creates the Express app
- App → API routes: mounts · App registers the versioned API router
- API routes → Auth: route · Feature route mounted under API path
- API routes → User: route · Feature route mounted under API path
- API routes → Products: route · Feature route mounted under API path
- API routes → Order: route · Feature route mounted under API path
- API routes → Payment: route · Feature route mounted under API path
- API routes → Coupon: route · Feature route mounted under API path
- API routes → OTP: route · Feature route mounted under API path
- API routes → Support: route · Feature route mounted under API path
- API routes → Stats: route · Feature route mounted under API path
- API routes → AI: route · Feature route mounted under API path
- Auth → JWT: tokens · JWT creation and session helpers
- Auth → Passport: oauth · Google OAuth integration
- Auth → Email: notify · Password reset and OTP email delivery
- User → Auth guard: protect · User routes require auth on private paths
- Products → Validate: validate · Catalog inputs are validated before service calls
- Products → Query builder: list · Product listing uses filtering and pagination
- Order → Stock update: inventory · Successful order flow reduces stock
- OTP → Email: deliver · OTP messages are sent by email
- Support → Validate: validate · Support requests are validated
- Errors → API routes: handle · Global failure handling wraps API routes
- App → Env config: config · Application reads runtime environment
- App → Redis: cache · App connects to Redis-backed state
- App → Cloudinary: media · App connects to hosted file storage
- App → Vercel: deploys · Application is hosted on Vercel