# bala177/retailx architecture

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

- Interactive diagram: https://gitdiagram.com/bala177/retailx
- Repository: https://github.com/bala177/retailx

## Overview

RetailX is a multi-tenant commerce platform with a customer storefront, store-admin panel, and Express API. The main customer journey selects a store, browses products or services, manages a cart, checks out, and reaches order confirmation; service stores also expose booking-oriented experiences. Store staff manage catalog and operations, while platform owners manage tenants and users. The API resolves tenant context and handles commerce and administration requests against MongoDB-backed models. Several backend handlers and pages were not sampled, so those subsystem links reflect documented capabilities and routing, not inspection of their implementations.

Main entry points: [`storefront/src/App.jsx`](https://github.com/bala177/retailx/blob/main/storefront/src/App.jsx) (Store routes), [`backend/src/routes/storeRoutes.js`](https://github.com/bala177/retailx/blob/main/backend/src/routes/storeRoutes.js) (Store endpoints), [`storefront/src/services/api.js`](https://github.com/bala177/retailx/blob/main/storefront/src/services/api.js) (Store API client), [`admin/src/App.jsx`](https://github.com/bala177/retailx/blob/main/admin/src/App.jsx) (Admin routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Customer storefront"]
  node_storefront_app["Store routes<br/>[App.jsx]"]
  node_store_context["Store selection<br/>[StoreContext.jsx]"]
  node_store_api["Store API client<br/>[api.js]"]
  node_catalog["Browse catalog<br/>[Products.jsx]"]
  node_service_experience["Service storefront<br/>[ServiceHome.jsx]"]
  node_cart["Cart state<br/>[CartContext.jsx]"]
  node_checkout["Checkout<br/>[Checkout.jsx]"]
  node_confirmation["Order confirmation"]
end

subgraph group_admin["Store administration"]
  node_admin_app["Admin routes<br/>[App.jsx]"]
  node_admin_auth["Admin identity<br/>[AuthContext.jsx]"]
  node_tenant_context["Tenant workspace<br/>[TenantContext.jsx]"]
  node_admin_api["Admin API client<br/>[api.js]"]
  node_store_operations["Store operations<br/>[Orders.jsx]"]
  node_platform_admin["Platform management"]
end

subgraph group_api["Backend API"]
  node_api_app["HTTP application<br/>[app.js]"]
  node_store_routes["Store endpoints<br/>[storeRoutes.js]"]
  node_platform_routes["Platform endpoints<br/>[platformRoutes.js]"]
  node_commerce_handlers["Commerce handlers"]
  node_review_handlers["Review handling"]
  node_platform_handlers["Platform handlers"]
  node_tenant_middleware["Tenant resolution<br/>[tenant.js]"]
  node_auth_handlers["Authentication<br/>[authController.js]"]
end

subgraph group_data["Tenant data"]
  node_db_connection[("MongoDB connection<br/>[database.js]")]
  node_models[("Commerce models")]
end

node_customer(("Shopper"))
node_mongo[("MongoDB")]

node_customer -->|"uses"| node_storefront_app
node_storefront_app -->|"checks store"| node_store_context
node_store_context -->|"loads store"| node_store_api
node_storefront_app -->|"routes to"| node_catalog
node_storefront_app -->|"routes to"| node_service_experience
node_catalog -->|"requests catalog"| node_store_api
node_storefront_app -->|"routes to"| node_cart
node_storefront_app -->|"routes to"| node_checkout
node_storefront_app -->|"routes to"| node_confirmation
node_checkout -.->|"submits order"| node_store_api
node_store_api -.->|"calls API"| node_store_routes
node_admin_app -->|"guards routes"| node_admin_auth
node_admin_app -->|"selects tenant"| node_tenant_context
node_tenant_context -->|"loads tenant"| node_admin_api
node_admin_app -->|"routes to"| node_store_operations
node_admin_app -->|"routes to"| node_platform_admin
node_api_app -->|"mounts routes"| node_store_routes
node_store_routes -->|"routes requests"| node_commerce_handlers
node_store_routes -->|"routes reviews"| node_review_handlers
node_api_app -.->|"mounts routes"| node_platform_routes
node_platform_routes -.->|"routes requests"| node_platform_handlers
node_commerce_handlers -->|"queries products"| node_models
node_review_handlers -->|"queries reviews"| node_models
node_platform_handlers -->|"queries tenants"| node_models
node_store_routes -.->|"resolves tenant"| node_tenant_middleware
node_admin_auth -->|"auth requests"| node_admin_api
node_db_connection -->|"connects"| node_mongo
node_models -.->|"persists records"| node_mongo
node_store_api -.->|"sends requests"| node_api_app
node_admin_api -.->|"sends requests"| node_api_app

click node_storefront_app "https://github.com/bala177/retailx/blob/main/storefront/src/App.jsx"
click node_store_context "https://github.com/bala177/retailx/blob/main/storefront/src/context/StoreContext.jsx"
click node_store_api "https://github.com/bala177/retailx/blob/main/storefront/src/services/api.js"
click node_catalog "https://github.com/bala177/retailx/blob/main/storefront/src/pages/Products.jsx"
click node_service_experience "https://github.com/bala177/retailx/blob/main/storefront/src/pages/ServiceHome.jsx"
click node_cart "https://github.com/bala177/retailx/blob/main/storefront/src/context/CartContext.jsx"
click node_checkout "https://github.com/bala177/retailx/blob/main/storefront/src/pages/Checkout.jsx"
click node_confirmation "https://github.com/bala177/retailx/blob/main/storefront/src/pages/OrderConfirmation.jsx"
click node_admin_app "https://github.com/bala177/retailx/blob/main/admin/src/App.jsx"
click node_admin_auth "https://github.com/bala177/retailx/blob/main/admin/src/context/AuthContext.jsx"
click node_tenant_context "https://github.com/bala177/retailx/blob/main/admin/src/context/TenantContext.jsx"
click node_admin_api "https://github.com/bala177/retailx/blob/main/admin/src/services/api.js"
click node_store_operations "https://github.com/bala177/retailx/blob/main/admin/src/pages/Orders.jsx"
click node_platform_admin "https://github.com/bala177/retailx/blob/main/admin/src/pages/SuperAdminStores.jsx"
click node_api_app "https://github.com/bala177/retailx/blob/main/backend/src/app.js"
click node_store_routes "https://github.com/bala177/retailx/blob/main/backend/src/routes/storeRoutes.js"
click node_platform_routes "https://github.com/bala177/retailx/blob/main/backend/src/routes/platformRoutes.js"
click node_commerce_handlers "https://github.com/bala177/retailx/blob/main/backend/src/controllers/productController.js"
click node_review_handlers "https://github.com/bala177/retailx/blob/main/backend/src/controllers/reviewController.js"
click node_platform_handlers "https://github.com/bala177/retailx/blob/main/backend/src/controllers/superAdminController.js"
click node_tenant_middleware "https://github.com/bala177/retailx/blob/main/backend/src/middleware/tenant.js"
click node_auth_handlers "https://github.com/bala177/retailx/blob/main/backend/src/controllers/authController.js"
click node_db_connection "https://github.com/bala177/retailx/blob/main/backend/src/config/database.js"
click node_models "https://github.com/bala177/retailx/tree/main/backend/src/models"

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_storefront_app,node_store_context,node_store_api,node_catalog,node_service_experience,node_cart,node_checkout,node_confirmation toneBlue
class node_admin_app,node_admin_auth,node_tenant_context,node_admin_api,node_store_operations,node_platform_admin,node_mongo toneAmber
class node_api_app,node_store_routes,node_platform_routes,node_commerce_handlers,node_review_handlers,node_platform_handlers,node_tenant_middleware,node_auth_handlers toneMint
class node_db_connection,node_models toneRose
class node_customer toneIndigo
```

## Components

### Customer storefront

- [Store routes](https://github.com/bala177/retailx/blob/main/storefront/src/App.jsx): `storefront/src/App.jsx`
- [Store selection](https://github.com/bala177/retailx/blob/main/storefront/src/context/StoreContext.jsx): `storefront/src/context/StoreContext.jsx`
- [Store API client](https://github.com/bala177/retailx/blob/main/storefront/src/services/api.js): `storefront/src/services/api.js`
- [Browse catalog](https://github.com/bala177/retailx/blob/main/storefront/src/pages/Products.jsx): `storefront/src/pages/Products.jsx`
- [Service storefront](https://github.com/bala177/retailx/blob/main/storefront/src/pages/ServiceHome.jsx): `storefront/src/pages/ServiceHome.jsx`
- [Cart state](https://github.com/bala177/retailx/blob/main/storefront/src/context/CartContext.jsx): `storefront/src/context/CartContext.jsx`
- [Checkout](https://github.com/bala177/retailx/blob/main/storefront/src/pages/Checkout.jsx): `storefront/src/pages/Checkout.jsx`
- [Order confirmation](https://github.com/bala177/retailx/blob/main/storefront/src/pages/OrderConfirmation.jsx): `storefront/src/pages/OrderConfirmation.jsx`

### Store administration

- [Admin routes](https://github.com/bala177/retailx/blob/main/admin/src/App.jsx): `admin/src/App.jsx`
- [Admin identity](https://github.com/bala177/retailx/blob/main/admin/src/context/AuthContext.jsx): `admin/src/context/AuthContext.jsx`
- [Tenant workspace](https://github.com/bala177/retailx/blob/main/admin/src/context/TenantContext.jsx): `admin/src/context/TenantContext.jsx`
- [Admin API client](https://github.com/bala177/retailx/blob/main/admin/src/services/api.js): `admin/src/services/api.js`
- [Store operations](https://github.com/bala177/retailx/blob/main/admin/src/pages/Orders.jsx): `admin/src/pages/Orders.jsx`
- [Platform management](https://github.com/bala177/retailx/blob/main/admin/src/pages/SuperAdminStores.jsx): `admin/src/pages/SuperAdminStores.jsx`

### Backend API

- [HTTP application](https://github.com/bala177/retailx/blob/main/backend/src/app.js): `backend/src/app.js`
- [Store endpoints](https://github.com/bala177/retailx/blob/main/backend/src/routes/storeRoutes.js): `backend/src/routes/storeRoutes.js`
- [Platform endpoints](https://github.com/bala177/retailx/blob/main/backend/src/routes/platformRoutes.js): `backend/src/routes/platformRoutes.js`
- [Commerce handlers](https://github.com/bala177/retailx/blob/main/backend/src/controllers/productController.js): `backend/src/controllers/productController.js`
- [Review handling](https://github.com/bala177/retailx/blob/main/backend/src/controllers/reviewController.js): `backend/src/controllers/reviewController.js`
- [Platform handlers](https://github.com/bala177/retailx/blob/main/backend/src/controllers/superAdminController.js): `backend/src/controllers/superAdminController.js`
- [Tenant resolution](https://github.com/bala177/retailx/blob/main/backend/src/middleware/tenant.js): `backend/src/middleware/tenant.js`
- [Authentication](https://github.com/bala177/retailx/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`

### Tenant data

- [MongoDB connection](https://github.com/bala177/retailx/blob/main/backend/src/config/database.js): `backend/src/config/database.js`
- [Commerce models](https://github.com/bala177/retailx/tree/main/backend/src/models): `backend/src/models`

### Other components

- **Shopper**
- **MongoDB**

## Connections

- Shopper → Store routes: uses (evidence: `storefront/src/App.jsx`)
- Store routes → Store selection: checks store (evidence: `storefront/src/App.jsx`)
- Store selection → Store API client: loads store (evidence: `storefront/src/context/StoreContext.jsx`)
- Store routes → Browse catalog: routes to (evidence: `storefront/src/App.jsx`)
- Store routes → Service storefront: routes to (evidence: `storefront/src/App.jsx`)
- Browse catalog → Store API client: requests catalog (evidence: `storefront/src/services/api.js`)
- Store routes → Cart state: routes to (evidence: `storefront/src/App.jsx`)
- Store routes → Checkout: routes to (evidence: `storefront/src/App.jsx`)
- Store routes → Order confirmation: routes to (evidence: `storefront/src/App.jsx`)
- Checkout → Store API client: submits order
- Store API client → Store endpoints: calls API
- Admin routes → Admin identity: guards routes (evidence: `admin/src/App.jsx`)
- Admin routes → Tenant workspace: selects tenant (evidence: `admin/src/App.jsx`)
- Tenant workspace → Admin API client: loads tenant (evidence: `admin/src/context/TenantContext.jsx`)
- Admin routes → Store operations: routes to (evidence: `admin/src/App.jsx`)
- Admin routes → Platform management: routes to (evidence: `admin/src/App.jsx`)
- HTTP application → Store endpoints: mounts routes (evidence: `backend/src/app.js`)
- Store endpoints → Commerce handlers: routes requests (evidence: `backend/src/routes/storeRoutes.js`)
- Store endpoints → Review handling: routes reviews (evidence: `backend/src/routes/storeRoutes.js`)
- HTTP application → Platform endpoints: mounts routes
- Platform endpoints → Platform handlers: routes requests
- Commerce handlers → Commerce models: queries products (evidence: `backend/src/controllers/productController.js`)
- Review handling → Commerce models: queries reviews (evidence: `backend/src/controllers/reviewController.js`)
- Platform handlers → Commerce models: queries tenants (evidence: `backend/src/controllers/superAdminController.js`)
- Store endpoints → Tenant resolution: resolves tenant
- Admin identity → Admin API client: auth requests (evidence: `admin/src/context/AuthContext.jsx`)
- MongoDB connection → MongoDB: connects (evidence: `backend/src/config/database.js`)
- Commerce models → MongoDB: persists records
- Store API client → HTTP application: sends requests
- Admin API client → HTTP application: sends requests
