# super-merch/supermerch-frontend architecture

> Architecture diagram of the GitHub repository super-merch/supermerch-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/super-merch/supermerch-frontend
- Repository: https://github.com/super-merch/supermerch-frontend

## Overview

#### Purpose and Runtime

PG Frontend is a Vite-built React 18 storefront for promotional merchandise. It provides catalog browsing, filtering, product customization/quotation, cart and Stripe-backed checkout, account/authentication, artwork upload, and a merch-assistant chat interface. It is deployed/configured for Vercel.

Entry bootstrap: `src/main.jsx` mounts the application; `src/App.jsx` composes routing and application-level UI. Route-level screens live under `src/pages/`.

#### Routing and Page Composition

Pages separate URL concerns from feature composition: home, shop/category listings, product details, cart, checkout, policy/support, auth, account, and post-order states.

Key paths:
- `src/App.jsx`
- `src/pages/Home/Home.jsx`
- `src/pages/ShopPage.jsx`
- `src/pages/ProducPage.jsx`
- `src/pages/CheckoutPage.jsx`

This is a client-side SPA using React Router. Common navigation, modal, transition, and reusable product UI sit between route pages and feature-specific components.

#### Product Discovery and Catalog Views

Catalog presentation is organized into home merchandising, shop/category results, and promotion-specific views. Shared filtering includes attributes, color, brand, price, and category mappings; listing UI consumes product/category data and renders cards or tabs.

Key paths:
- `src/components/shop/ProductDisplay.jsx`
- `src/components/shop/Sidebar.jsx`
- `src/components/shared/UnifiedSidebar.jsx`
- `src/components/shared/AttributeFilters.jsx`
- `src/config/routeCategoryMapping.js`

Product state and filter choices cross this boundary through Redux rather than being confined to individual listing components.

#### Product Detail, Customization, and Quotes

The product-detail feature owns gallery, pricing, decoration, shipping, lead-time, specifications, size-guide, and order-summary interactions. Quote capture is modal-driven, while artwork upload is exposed as its own routed journey.

Key paths:
- `src/components/product/ProductDetails/index.jsx`
- `src/components/product/ProductDetails/PricingTab.jsx`
- `src/components/product/QuoteFormModal.jsx`
- `src/pages/UploadArtwork.jsx`

This layer turns selected catalog items and customer options into cart- or quote-oriented actions; backend integration is expected through the configured API base URL.

#### Commerce State and Checkout

Redux Toolkit centralizes cart, category, favorites, filters, and promotional state. The checkout UI is a staged workflow for customer, shipping, billing, payment, and order-summary collection. Stripe is client-side payment infrastructure; the backend must create/respond with the required checkout session/payment data.

Key paths:
- `src/redux/store.js`
- `src/redux/slices/cartSlice.js`
- `src/redux/slices/filterSlice.js`
- `src/components/cart/CartComponent.jsx`
- `src/components/checkout/Checkout.jsx`
- `src/components/checkout/CheckoutSteps/PaymentStep.jsx`

#### Identity and Account Boundary

Authentication is managed through React context and hooks, with auth layout/modals for login, Google auth, password entry/reset, and signup. Account pages provide dashboard, profile/address, order, and user-product surfaces.

Key paths:
- `src/context/AuthContext.jsx`
- `src/hooks/useAuth.js`
- `src/components/auth/AuthLayout.jsx`
- `src/pages/Login.jsx`
- `src/userAdmin/DashBoard.jsx`

#### External Services and Operations

The frontend reads Vite-exposed environment settings for the backend (`VITE_BACKEND_URL`), Stripe publishable key (`VITE_STRIPE_PUBLIC_KEY`), and SuperMerch Bot endpoint (`VITE_BOT_API_URL`). The chat widget persists a session ID in browser `localStorage` and sends it as `X-Session-Id`, allowing conversational refinement and product-card responses.

Key paths:
- `src/components/Chat/ChatWidget.jsx`
- `.env.example`
- `vite.config.js`
- `vercel.json`

Main entry points: [`src/components/product/ProductDetails/index.jsx`](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/product/ProductDetails/index.jsx) (Customization & pricing), [`src/pages/Home/Home.jsx`](https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/Home/Home.jsx) (Route screens), [`src/pages/ShopPage.jsx`](https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/ShopPage.jsx) (Shop results), [`src/components/cart/CartComponent.jsx`](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/cart/CartComponent.jsx) (Cart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["React SPA"]
  node_bootstrap(("Vite bootstrap<br/>entry<br/>[main.jsx]"))
  node_app_router["App routes &amp; shell<br/>router<br/>[App.jsx]"]
  node_page_routes["Route screens<br/>pages<br/>[Home.jsx]"]
  node_chat["Merch assistant chat<br/>feature<br/>[ChatWidget.jsx]"]
end

subgraph group_catalog["Catalog &amp; Product"]
  node_shop_page["Shop results<br/>page<br/>[ShopPage.jsx]"]
  node_product_page["Product page<br/>[ProducPage.jsx]"]
  node_catalog_listing["Catalog listing UI<br/>components<br/>[ProductDisplay.jsx]"]
  node_filtering["Filters &amp; category mapping<br/>components"]
  node_product_details["Customization &amp; pricing<br/>feature<br/>[index.jsx]"]
  node_quote_modal["Quote capture<br/>feature<br/>[QuoteFormModal.jsx]"]
  node_artwork_upload["Artwork upload<br/>page<br/>[UploadArtwork.jsx]"]
end

subgraph group_commerce["Commerce"]
  node_redux_store[("Redux state<br/>[store.js]")]
  node_cart["Cart<br/>feature<br/>[CartComponent.jsx]"]
  node_checkout["Staged checkout<br/>feature<br/>[Checkout.jsx]"]
end

subgraph group_identity["Identity"]
  node_auth_context[("Auth context<br/>state<br/>[AuthContext.jsx]")]
  node_auth_ui["Auth flows<br/>components<br/>[AuthLayout.jsx]"]
  node_account["Account dashboard<br/>page<br/>[DashBoard.jsx]"]
end

subgraph group_external["External Services"]
  node_stripe{{"Stripe<br/>payment-service"}}
  node_backend_api{{"Backend API<br/>external-api"}}
  node_bot_api{{"SuperMerch Bot API<br/>external-api"}}
  node_vercel{{"Vercel deployment<br/>[vercel.json]"}}
end

node_bootstrap -->|"mounts"| node_app_router
node_app_router -->|"routes to"| node_page_routes
node_page_routes -->|"shop route"| node_shop_page
node_page_routes -->|"product route"| node_product_page
node_shop_page -->|"composes"| node_catalog_listing
node_shop_page -->|"uses"| node_filtering
node_catalog_listing -->|"reads catalog state"| node_redux_store
node_filtering -->|"updates filters"| node_redux_store
node_product_page -->|"composes"| node_product_details
node_product_details -->|"opens"| node_quote_modal
node_product_details -->|"adds configured item"| node_cart
node_product_details -->|"starts upload"| node_artwork_upload
node_cart -->|"reads and updates"| node_redux_store
node_cart -->|"proceeds to"| node_checkout
node_checkout -->|"collects payment"| node_stripe
node_checkout -->|"creates checkout data"| node_backend_api
node_product_details -->|"product and quote requests"| node_backend_api
node_auth_ui -->|"authenticates through"| node_auth_context
node_account -->|"uses session"| node_auth_context
node_chat -->|"session chat requests"| node_bot_api
node_vercel -.->|"deploys"| node_app_router

click node_bootstrap "https://github.com/super-merch/supermerch-frontend/blob/main/src/main.jsx"
click node_app_router "https://github.com/super-merch/supermerch-frontend/blob/main/src/App.jsx"
click node_page_routes "https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/Home/Home.jsx"
click node_shop_page "https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/ShopPage.jsx"
click node_product_page "https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/ProducPage.jsx"
click node_catalog_listing "https://github.com/super-merch/supermerch-frontend/blob/main/src/components/shop/ProductDisplay.jsx"
click node_filtering "https://github.com/super-merch/supermerch-frontend/blob/main/src/components/shared/AttributeFilters.jsx"
click node_product_details "https://github.com/super-merch/supermerch-frontend/blob/main/src/components/product/ProductDetails/index.jsx"
click node_quote_modal "https://github.com/super-merch/supermerch-frontend/blob/main/src/components/product/QuoteFormModal.jsx"
click node_artwork_upload "https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/UploadArtwork.jsx"
click node_redux_store "https://github.com/super-merch/supermerch-frontend/blob/main/src/redux/store.js"
click node_cart "https://github.com/super-merch/supermerch-frontend/blob/main/src/components/cart/CartComponent.jsx"
click node_checkout "https://github.com/super-merch/supermerch-frontend/blob/main/src/components/checkout/Checkout.jsx"
click node_auth_context "https://github.com/super-merch/supermerch-frontend/blob/main/src/context/AuthContext.jsx"
click node_auth_ui "https://github.com/super-merch/supermerch-frontend/blob/main/src/components/auth/AuthLayout.jsx"
click node_account "https://github.com/super-merch/supermerch-frontend/blob/main/src/userAdmin/DashBoard.jsx"
click node_chat "https://github.com/super-merch/supermerch-frontend/blob/main/src/components/Chat/ChatWidget.jsx"
click node_vercel "https://github.com/super-merch/supermerch-frontend/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_bootstrap,node_app_router,node_page_routes,node_chat toneBlue
class node_shop_page,node_product_page,node_catalog_listing,node_filtering,node_product_details,node_quote_modal,node_artwork_upload toneAmber
class node_redux_store,node_cart,node_checkout toneMint
class node_auth_context,node_auth_ui,node_account toneRose
class node_stripe,node_backend_api,node_bot_api,node_vercel toneIndigo
```

## Components

### React SPA

- [Vite bootstrap](https://github.com/super-merch/supermerch-frontend/blob/main/src/main.jsx): entry · Mounts the React application. · `src/main.jsx`
- [App routes & shell](https://github.com/super-merch/supermerch-frontend/blob/main/src/App.jsx): router · Composes React Router and application UI. · `src/App.jsx`
- [Route screens](https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/Home/Home.jsx): pages · Home, shop, product, checkout, auth, and account journeys. · `src/pages/Home/Home.jsx`
- [Merch assistant chat](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/Chat/ChatWidget.jsx): feature · Persists a browser session ID and renders conversational product responses. · `src/components/Chat/ChatWidget.jsx`

### Catalog & Product

- [Shop results](https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/ShopPage.jsx): page · Category and search-oriented catalog view. · `src/pages/ShopPage.jsx`
- [Product page](https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/ProducPage.jsx): page · Product-detail route composition. · `src/pages/ProducPage.jsx`
- [Catalog listing UI](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/shop/ProductDisplay.jsx): components · Renders product cards and listing views. · `src/components/shop/ProductDisplay.jsx`
- [Filters & category mapping](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/shared/AttributeFilters.jsx): components · Attribute filters and route-category mappings. · `src/components/shared/AttributeFilters.jsx`
- [Customization & pricing](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/product/ProductDetails/index.jsx): feature · Handles detail, pricing, decoration, shipping, and order options. · `src/components/product/ProductDetails/index.jsx`
- [Quote capture](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/product/QuoteFormModal.jsx): feature · Modal quote request flow. · `src/components/product/QuoteFormModal.jsx`
- [Artwork upload](https://github.com/super-merch/supermerch-frontend/blob/main/src/pages/UploadArtwork.jsx): page · Routed artwork submission journey. · `src/pages/UploadArtwork.jsx`

### Commerce

- [Redux state](https://github.com/super-merch/supermerch-frontend/blob/main/src/redux/store.js): state · Central cart, category, favorites, filters, and promotion state. · `src/redux/store.js`
- [Cart](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/cart/CartComponent.jsx): feature · Cart display and cart actions. · `src/components/cart/CartComponent.jsx`
- [Staged checkout](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/checkout/Checkout.jsx): feature · Collects customer, shipping, billing, payment, and order data. · `src/components/checkout/Checkout.jsx`

### Identity

- [Auth context](https://github.com/super-merch/supermerch-frontend/blob/main/src/context/AuthContext.jsx): state · Provides authentication state through context and hooks. · `src/context/AuthContext.jsx`
- [Auth flows](https://github.com/super-merch/supermerch-frontend/blob/main/src/components/auth/AuthLayout.jsx): components · Login, Google auth, password reset, and signup UI. · `src/components/auth/AuthLayout.jsx`
- [Account dashboard](https://github.com/super-merch/supermerch-frontend/blob/main/src/userAdmin/DashBoard.jsx): page · User dashboard, profile, addresses, orders, and products. · `src/userAdmin/DashBoard.jsx`

### External Services

- **Stripe**: payment-service · Client payment infrastructure using backend-provided payment data.
- **Backend API**: external-api · Configured through VITE_BACKEND_URL for product, quote, and checkout operations.
- **SuperMerch Bot API**: external-api · Configured through VITE_BOT_API_URL and receives X-Session-Id.
- [Vercel deployment](https://github.com/super-merch/supermerch-frontend/blob/main/vercel.json): deployment · Deployment configuration for the SPA. · `vercel.json`

## Connections

- Vite bootstrap → App routes & shell: mounts
- App routes & shell → Route screens: routes to
- Route screens → Shop results: shop route
- Route screens → Product page: product route
- Shop results → Catalog listing UI: composes
- Shop results → Filters & category mapping: uses
- Catalog listing UI → Redux state: reads catalog state
- Filters & category mapping → Redux state: updates filters
- Product page → Customization & pricing: composes
- Customization & pricing → Quote capture: opens
- Customization & pricing → Cart: adds configured item
- Customization & pricing → Artwork upload: starts upload
- Cart → Redux state: reads and updates
- Cart → Staged checkout: proceeds to
- Staged checkout → Stripe: collects payment
- Staged checkout → Backend API: creates checkout data
- Customization & pricing → Backend API: product and quote requests
- Auth flows → Auth context: authenticates through
- Account dashboard → Auth context: uses session
- Merch assistant chat → SuperMerch Bot API: session chat requests
- Vercel deployment → App routes & shell: deploys