# masudrana430/thornview-grocery-client architecture

> Architecture diagram of the GitHub repository masudrana430/thornview-grocery-client, 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/masudrana430/thornview-grocery-client
- Repository: https://github.com/masudrana430/thornview-grocery-client

## Overview

1. **What this repo is**
   - THORNVIEW GROCERY is a React/Vite frontend for a grocery eCommerce platform with distinct customer and back-office experiences.
   - The repo is frontend-heavy, but it is clearly designed to talk to a separate Node/Express/MongoDB backend through API wrappers, auth helpers, Stripe, Socket.IO, and Firebase Auth.

2. **Application shell and bootstrapping**
   - The app starts in `src/main.jsx`, with global styling in `src/index.css` and `src/App.css`.
   - Route composition lives in `src/Routes/Routes.jsx`, while layout-level composition is split into `MainLayout`, `AuthLayout`, and `AdminLayout` under `src/Layouts`.
   - Firebase hosting is used for deployment (`firebase.json`, `.firebaserc`, `public/_redirects`).

3. **Cross-cutting state and providers**
   - Global app state is centralized in `src/Provider` and `src/context`.
   - The main shared concerns are authentication (`AuthProvider`), cart state (`CartProvider` / `CartContext`), and theme (`ThemeProvider`).
   - `AppProviders` and `RootProviders` likely compose these wrappers so routing and pages can assume auth/cart/theme are already available.

4. **Route protection and role boundaries**
   - Protected access is enforced through route-guard components in both `src/Provider` and `src/Routes`, including `RequireAuth`, `AdminRoute`, `AdminGate`, and `PrivatRoute`.
   - The architecture is role-based, matching the README’s Admin / Manager / Customer / Marketer model.
   - This means the diagram should show a clear boundary between public pages, authenticated customer pages, and privileged admin pages.

5. **Customer commerce flow**
   - The customer-facing path is centered on `Home`, `ShopResults`, `ProductDetails`, `CartPage`, `CheckoutPage`, and order-result pages (`OrderSuccess`, `OrderFailed`, `OrderDetailsPage`).
   - Cart state is shared through the cart provider and surfaced in `CartDrawer` plus page-level cart views.
   - Checkout is a dedicated subsystem with address entry, delivery slot selection, order summary, and Stripe payment form components under `src/Pages/Checkout/components`.

6. **Authentication and account area**
   - Auth entry points are `Login`, `Register`, and `ForgotPassword`, with user profile and order history in `Profile` and `Account/MyOrdersPage`.
   - The frontend integrates Firebase Auth via `src/firebase/firebase.config.js`, but the app also appears to rely on backend user/session APIs through helper layers.
   - This suggests a split auth boundary: identity/session management at the client edge, persisted authorization and user metadata on the API side.

7. **Admin dashboard subsystem**
   - The admin area is organized under `src/Pages/Admin`, with dedicated pages for dashboard, products, orders, users, customers, inventory, live chat, and banner/content management.
   - Reusable admin UI lives in `src/Pages/Admin/components` such as `DataTable`, `Pagination`, `ProductForm`, and `SearchFilters`.
   - Product CRUD is a major subsystem: list, create, edit, inventory adjustments, and likely backend synchronization for catalog operations.

8. **Home page merchandising and content blocks**
   - The home experience is built from composable merchandising sections in `src/Pages/Home/components` and shared hero/banner components in `src/Components`.
   - Examples include hero rails, product rails/strips, promo mosaics, department scrollers, brand banners, and support banners.
   - This is a content-driven storefront layout, not a single monolithic page.

9. **Real-time support and AI-assisted chat**
   - Live chat is a distinct subsystem spanning `src/Components/Chat`, `src/Pages/Admin/LiveChat.jsx`, `SeedChatButton.jsx`, and socket utilities in `src/lib/socket.js` and `src/services/socket.js`.
   - The README’s Gemini API support suggests chat can be augmented with AI-generated responses or quick replies.
   - The architecture should show customer chat UI talking to a Socket.IO channel, with admin-side monitoring/response tooling.

10. **Payments, address, and location intelligence**
   - Checkout has a strong fulfillment focus: address form, delivery slot picker, and Stripe payment integration (`src/lib/stripe.js`, `StripeCheckout.jsx`).
   - The README mentions geolocation, Leaflet, and reverse geocoding; the presence of `bdLocations.json` suggests location-specific address support is embedded in the UX.
   - This is a meaningful boundary because shipping/address logic is separated from product browsing and from payment processing.

11. **API and data access layer**
   - Network access is abstracted in `src/services/api.js`, `src/services/apiClient.js`, `src/utils/authFetch.js`, and hooks such as `useAxiosSecure`.
   - Data-fetching concerns are likely centralized to keep pages/components focused on rendering rather than request plumbing.
   - There is also a `useDebounce` hook, which supports search/filter-heavy flows like shop results and admin lists.

12. **UI component system**
   - Shared presentational components live in `src/Components`, covering the header, footer, banners, cart drawer, loaders, theme toggle, scroll-to-top, and address modal.
   - The header is decomposed into Walmart-style subparts: top utility bar, search box, and mega menu.
   - Multiple spinner variants suggest different loading states for home, general content, and secondary flows.

13. **Static assets and content**
   - `public/appData.json` and the many Lottie JSON files in `src/animation` indicate a content-rich UI with animated empty states, loading, success, and error visuals.
   - `src/data/bdLocations.json` is a local dataset supporting location/address workflows.
   - `Hero IO.fig` indicates design handoff/source material rather than runtime architecture.

14. **Deployment and environment boundaries**
   - The app is configured for Firebase Hosting, but it depends on external backend services for commerce data, auth/session handling, payments, and chat.
   - The important runtime boundaries for a diagram are: browser React app, Firebase Auth, REST/API backend, Socket.IO realtime channel, Stripe payment service, and Gemini AI service.
   - The frontend is the orchestration layer that ties all of those services into a single retail workflow.

Main entry points: [`src/services`](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/services) (Services), [`src/Components`](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Components) (Shared UI), [`src/Provider`](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Provider) (Providers), [`src/Pages/Checkout/CheckoutPage.jsx`](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Checkout/CheckoutPage.jsx) (Checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_main(("Entry<br/>React boot<br/>[main.jsx]"))
  node_routes["Routes<br/>Route map<br/>[Routes.jsx]"]
  node_layouts["Layouts"]
  node_providers["Providers<br/>App context"]
  node_guards{{"Access guards<br/>Route guards"}}
end

subgraph group_customer["Customer flow"]
  node_home["Home<br/>Merchandising<br/>[Home.jsx]"]
  node_shop["Shop results<br/>Catalog browse<br/>[ShopResults.jsx]"]
  node_product["Product details<br/>Product view<br/>[ProductDetails.jsx]"]
  node_cart["Cart<br/>[CartPage.jsx]"]
  node_checkout["Checkout<br/>Fulfillment<br/>[CheckoutPage.jsx]"]
  node_orders["Orders<br/>Post-purchase"]
  node_account["Account<br/>Profile area<br/>[Profile.jsx]"]
  node_auth["Auth pages<br/>Login/signup<br/>[Login.jsx]"]
end

subgraph group_admin["Admin ops"]
  node_adminhome["Dashboard<br/>Admin overview"]
  node_catalog["Catalog ops<br/>Admin CRUD"]
  node_ordersadmin["Order ops<br/>Admin orders"]
  node_users["User ops<br/>Admin users<br/>[AdminUsersPage.jsx]"]
  node_chat["Live chat<br/>Realtime support<br/>[LiveChat.jsx]"]
end

subgraph group_shared["Shared UI"]
  node_ui["Shared UI<br/>Components"]
  node_services["Services<br/>API layer"]
end

subgraph group_data["Data & deploy"]
  node_firebase[("Firebase auth<br/>Client auth<br/>[firebase.config.js]")]
  node_locations["Location data<br/>Local dataset<br/>[bdLocations.json]"]
  node_hosting["Hosting<br/>Deploy config<br/>[firebase.json]"]
end

node_main -->|"wraps"| node_providers
node_main -->|"renders"| node_routes
node_routes -->|"uses"| node_layouts
node_routes -->|"protects"| node_guards
node_providers -->|"auth"| node_firebase
node_providers -->|"state/data"| node_services
node_providers -->|"theme/cart"| node_ui
node_layouts -->|"frames"| node_ui
node_home -->|"composes"| node_ui
node_home -->|"loads"| node_services
node_shop -->|"queries"| node_services
node_shop -->|"filters"| node_ui
node_product -->|"loads"| node_services
node_cart -->|"drawer/page"| node_ui
node_checkout -->|"payments"| node_services
node_checkout -->|"addresses"| node_locations
node_checkout -->|"forms"| node_ui
node_orders -->|"status"| node_services
node_account -->|"profile"| node_services
node_auth -->|"sign in"| node_firebase
node_auth -->|"session"| node_services
node_adminhome -->|"metrics"| node_services
node_catalog -->|"crud"| node_services
node_ordersadmin -->|"manage"| node_services
node_users -->|"manage"| node_services
node_chat -->|"realtime"| node_services
node_chat -->|"widgets"| node_ui
node_services -.->|"deploy"| node_hosting

click node_main "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/main.jsx"
click node_routes "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Routes/Routes.jsx"
click node_layouts "https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Layouts"
click node_providers "https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Provider"
click node_guards "https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Provider"
click node_home "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Home/Home.jsx"
click node_shop "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Shop/ShopResults.jsx"
click node_product "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Product/ProductDetails.jsx"
click node_cart "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Cart/CartPage.jsx"
click node_checkout "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Checkout/CheckoutPage.jsx"
click node_orders "https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Pages/Orders"
click node_account "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Profile.jsx"
click node_auth "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Login.jsx"
click node_adminhome "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Admin/AdminDashboardPage.jsx"
click node_catalog "https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Pages/Admin/Products"
click node_ordersadmin "https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Pages/Admin/Orders"
click node_users "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Admin/AdminUsersPage.jsx"
click node_chat "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Admin/LiveChat.jsx"
click node_ui "https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Components"
click node_services "https://github.com/masudrana430/thornview-grocery-client/tree/main/src/services"
click node_firebase "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/firebase/firebase.config.js"
click node_locations "https://github.com/masudrana430/thornview-grocery-client/blob/main/src/data/bdLocations.json"
click node_hosting "https://github.com/masudrana430/thornview-grocery-client/blob/main/firebase.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_main,node_routes,node_layouts,node_providers,node_guards toneBlue
class node_home,node_shop,node_product,node_cart,node_checkout,node_orders,node_account,node_auth toneAmber
class node_adminhome,node_catalog,node_ordersadmin,node_users,node_chat toneMint
class node_ui,node_services toneRose
class node_firebase,node_locations,node_hosting toneIndigo
```

## Components

### App shell

Bootstrapping, routing, layouts, and providers.

- [Entry](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/main.jsx): React boot · Vite entrypoint that mounts the app and global styles. · `src/main.jsx`
- [Routes](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Routes/Routes.jsx): Route map · Top-level route composition for public, auth, customer, and admin areas. · `src/Routes/Routes.jsx`
- [Layouts](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Layouts): Shell layouts · Main, auth, and admin layouts that frame page content. · `src/Layouts`
- [Providers](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Provider): App context · Composes auth, cart, theme, and root-level wrappers. · `src/Provider`
- [Access guards](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Provider): Route guards · Public/auth/admin protection components used to enforce role boundaries. · `src/Provider`

### Customer flow

Storefront, cart, checkout, orders, and account area.

- [Home](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Home/Home.jsx): Merchandising · Content-rich storefront landing page assembled from reusable sections. · `src/Pages/Home/Home.jsx`
- [Shop results](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Shop/ShopResults.jsx): Catalog browse · Search and filter results for product discovery. · `src/Pages/Shop/ShopResults.jsx`
- [Product details](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Product/ProductDetails.jsx): Product view · Single product detail experience feeding cart and purchase flow. · `src/Pages/Product/ProductDetails.jsx`
- [Cart](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Cart/CartPage.jsx): Cart flow · Cart page that reflects shared cart state and prepares checkout. · `src/Pages/Cart/CartPage.jsx`
- [Checkout](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Checkout/CheckoutPage.jsx): Fulfillment · Address, delivery slot, order summary, and payment orchestration. · `src/Pages/Checkout/CheckoutPage.jsx`
- [Orders](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Pages/Orders): Post-purchase · Success, failure, and order detail views after checkout. · `src/Pages/Orders`
- [Account](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Profile.jsx): Profile area · Customer profile and order history. · `src/Pages/Profile.jsx`
- [Auth pages](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Login.jsx): Login/signup · Login, register, and password recovery entry points. · `src/Pages/Login.jsx`

### Admin ops

Back-office dashboard, catalog, orders, users, inventory, and chat.

- [Dashboard](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Admin/AdminDashboardPage.jsx): Admin overview · Back-office landing page for operational monitoring. · `src/Pages/Admin/AdminDashboardPage.jsx`
- [Catalog ops](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Pages/Admin/Products): Admin CRUD · Product list, create/edit, and inventory adjustment workflow. · `src/Pages/Admin/Products`
- [Order ops](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Pages/Admin/Orders): Admin orders · Order list and order detail management for staff. · `src/Pages/Admin/Orders`
- [User ops](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Admin/AdminUsersPage.jsx): Admin users · Customer and user management views. · `src/Pages/Admin/AdminUsersPage.jsx`
- [Live chat](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/Pages/Admin/LiveChat.jsx): Realtime support · Customer support chat UI and admin-side chat console. · `src/Pages/Admin/LiveChat.jsx`

### Shared UI

Reusable components, utilities, and cross-cutting services.

- [Shared UI](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/Components): Components · Header, footer, drawers, banners, chat widgets, and loading states. · `src/Components`
- [Services](https://github.com/masudrana430/thornview-grocery-client/tree/main/src/services): API layer · API client wrappers, auth fetch helpers, socket utilities, and Stripe integration. · `src/services`

### Data & deploy

Local data, auth config, and hosting-related assets.

- [Firebase auth](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/firebase/firebase.config.js): Client auth · Firebase authentication configuration used by the frontend. · `src/firebase/firebase.config.js`
- [Location data](https://github.com/masudrana430/thornview-grocery-client/blob/main/src/data/bdLocations.json): Local dataset · Bangladesh location/address dataset supporting checkout and address entry. · `src/data/bdLocations.json`
- [Hosting](https://github.com/masudrana430/thornview-grocery-client/blob/main/firebase.json): Deploy config · Firebase hosting and SPA redirect configuration. · `firebase.json`

## Connections

- Entry → Providers: wraps · App bootstraps global providers before rendering routes.
- Entry → Routes: renders · Main mounts the routed application.
- Routes → Layouts: uses · Routes compose page shells through layout boundaries.
- Routes → Access guards: protects · Route map applies auth and admin gating.
- Providers → Firebase auth: auth · Auth provider integrates Firebase identity state.
- Providers → Services: state/data · Shared providers depend on API and session helpers.
- Providers → Shared UI: theme/cart · Providers support UI components with shared state.
- Layouts → Shared UI: frames · Layouts assemble header, footer, drawers, and page chrome.
- Home → Shared UI: composes · Home is built from reusable merchandising components.
- Home → Services: loads · Home sections fetch product and content data.
- Shop results → Services: queries · Shop browsing uses the API layer for catalog search.
- Shop results → Shared UI: filters · Search-heavy UI uses shared controls and loaders.
- Product details → Services: loads · Product details fetch catalog and related data.
- Cart → Shared UI: drawer/page · Cart state is surfaced through shared cart UI.
- Checkout → Services: payments · Checkout calls Stripe and backend order APIs.
- Checkout → Location data: addresses · Address entry uses local location data.
- Checkout → Shared UI: forms · Checkout reuses address and summary components.
- Orders → Services: status · Order result pages reflect backend order state.
- Account → Services: profile · Account area reads user and order history data.
- Auth pages → Firebase auth: sign in · Login and registration integrate Firebase auth.
- Auth pages → Services: session · Auth pages also interact with backend user/session APIs.
- Dashboard → Services: metrics · Dashboard loads operational data from APIs.
- Catalog ops → Services: crud · Catalog operations use the API layer for product management.
- Order ops → Services: manage · Order admin screens read and update order data.
- User ops → Services: manage · User administration uses backend access.
- Live chat → Services: realtime · Live chat connects through socket and backend helpers.
- Live chat → Shared UI: widgets · Chat is exposed through floating and admin-facing UI components.
- Services → Hosting: deploy · Frontend is configured for Firebase-hosted deployment.