# dustopia1203/hhm-fe architecture

> Architecture diagram of the GitHub repository dustopia1203/hhm-fe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dustopia1203/hhm-fe
- Repository: https://github.com/dustopia1203/hhm-fe

## Overview

##### Project type and purpose
- This is a client-side Single Page Application built with React + TypeScript, bundled by Vite.
- It implements an e-commerce storefront: user account management, product/catalog browsing, shopping cart, checkout/payment flows (including Solana and VNPAY callbacks), order management, product reviews, and vendor/shop dashboards.

##### File structure
- Top-level “public” contains static assets and index.html.
- “src” is the application code:
- apis/ – a thin REST client layer (axiosClient + useXxxApis hooks)
- components/ – reusable UI pieces (common, UI primitives, domain features)
- routes/ – file-based routing: auth, products, cart, orders, payment callbacks, vendor shop area
- stores/ – client state management (e.g. Zustand or similar hooks)
- utils/ & lib/ – assorted helpers (auth helpers, Cloudinary integration, search utils)
- main.tsx & routeTree.gen.ts – Vite entry point and generated route manifest for the router.
- Config files: vite.config.ts, tsconfig*.json, eslint.config.js.

##### README for additional insights
- It’s a minimal Vite + React + TypeScript starter, with recommendations for ESLint.
- No backend code lives here; all server interactions go through the REST hooks in src/apis.

##### Main components
a. Frontend SPA (React + Vite)
– Entry: index.html → main.tsx → React application
– Router & routeTree.gen.ts → dynamic route resolution
– UI layers:
- Domain pages (Login, Register, ProductList, Checkout, ShopDashboard, etc.)
- Reusable components (ProductCard, ReviewForm, Header/Footer, Loader, NotFound)
- UI primitives (dialog, sonner notifications)
– State stores (useProfileStore, useShopStore)
– API client layer (axiosClient + useAccountApis, useCartApis, usePaymentApis, etc.)
– Utility modules (auth token management, Cloudinary image uploads, client-side search)
b. Backend REST services
– User service (account creation, login, verify-account)
– Product/Catalog service (categories, products, reviews)
– Cart service
– Order service
– Payment service (checkout initiation, Solana & VNPAY callbacks)
– Shop service (vendor-specific data, shop settings)
– Shipping service
c. External third-party services
– Cloudinary (image hosting)
– Payment gateways (Solana network, VNPAY)

##### Relationships and data flow
- User interacts with SPA in browser → React router resolves route → React components call hooks in src/apis → axiosClient sends HTTP requests to backend service endpoints → backend returns JSON → hooks update UI and stores → UI renders updated state.
- For uploads: React component invokes utils/cloudinary.ts to upload images → Cloudinary responds with URL → URL passed to product/shop APIs.
- Checkout flow: React component invokes usePaymentApis → backend returns payment URL or transaction details → browser redirects to gateway → gateway calls back to /payment/solana-callback or /payment/vnpay-callback → React route handler finalizes order via order API.

##### Architectural patterns & principles
- Layered architecture: Presentation (components & routes) → Application (hooks & stores) → Infrastructure (axiosClient) → External services.
- Separation of concerns: UI components vs. domain pages vs. API hooks vs. utility modules.
- File-based routing for automatic route registration (routeTree.gen.ts).
- Single source of truth for API base URL and interceptors in axiosClient.
- Local state stores for profile & shop context.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Frontend SPA
  subgraph "Frontend SPA" 
    direction TB

    subgraph "Entry & Bootstrap"
      BROWSER(["Browser / User Interface"]):::frontend
      INDEX["index.html"]:::frontend
      MAIN["main.tsx"]:::frontend
    end

    subgraph "Routing"
      ROUTE_MANIFEST["routeTree.gen.ts"]:::frontend
      ROUTES["Routes (src/routes)"]:::frontend
    end

    subgraph "UI Layers"
      COMPONENTS_COMMON["Common Components"]:::frontend
      COMPONENTS_FEATURES["Feature Components"]:::frontend
      COMPONENTS_UI["UI Primitives"]:::frontend
    end

    subgraph "State Stores"
      STORE_PROFILE["useProfileStore"]:::frontend
      STORE_SHOP["useShopStore"]:::frontend
    end

    subgraph "API Layer"
      AXIOS["axiosClient"]:::api
      HOOK_ACCOUNT["useAccountApis"]:::api
      HOOK_CATEGORY["useCategoryApis"]:::api
      HOOK_PRODUCT["useProductApis"]:::api
      HOOK_REVIEW["useReviewApis"]:::api
      HOOK_CART["useCartApis"]:::api
      HOOK_ORDER["useOrderApis"]:::api
      HOOK_PAYMENT["usePaymentApis"]:::api
      HOOK_SHOP["useShopApis"]:::api
      HOOK_SHIPPING["useShippingApis"]:::api
    end

    subgraph "Utilities"
      UTIL_AUTH["auth.ts"]:::frontend
      UTIL_CLOUDINARY["cloudinary.ts"]:::frontend
      UTIL_SEARCH["searchUtils.ts"]:::frontend
      UTIL_MISC["misc utils"]:::frontend
    end
  end

  %% Backend Services
  subgraph "REST Backend Services"
    direction TB
    USER_SVC["User Service"]:::backend
    PRODUCT_SVC["Product/Catalog Service"]:::backend
    CART_SVC["Cart Service"]:::backend
    ORDER_SVC["Order Service"]:::backend
    PAYMENT_SVC["Payment Service"]:::backend
    SHOP_SVC["Shop Service"]:::backend
    SHIPPING_SVC["Shipping Service"]:::backend
  end

  %% External Services
  subgraph "External Services"
    direction TB
    CLOUDINARY["Cloudinary"]:::external
    SOLANA["Solana Network"]:::external
    VNPAY["VNPAY Gateway"]:::external
  end

  %% Data Flows
  BROWSER -->|loads| INDEX
  INDEX --> MAIN
  MAIN --> ROUTE_MANIFEST
  MAIN --> ROUTES
  ROUTES --> COMPONENTS_COMMON
  ROUTES --> COMPONENTS_FEATURES
  ROUTES --> COMPONENTS_UI
  COMPONENTS_FEATURES --> STORE_PROFILE
  COMPONENTS_FEATURES --> STORE_SHOP
  COMPONENTS_FEATURES --> AXIOS
  COMPONENTS_COMMON --> AXIOS
  COMPONENTS_UI --> AXIOS
  STORE_PROFILE --> AXIOS
  STORE_SHOP --> AXIOS

  AXIOS --> USER_SVC
  AXIOS --> PRODUCT_SVC
  AXIOS --> CART_SVC
  AXIOS --> ORDER_SVC
  AXIOS --> PAYMENT_SVC
  AXIOS --> SHOP_SVC
  AXIOS --> SHIPPING_SVC

  USER_SVC -->|JSON| AXIOS
  PRODUCT_SVC -->|JSON| AXIOS
  CART_SVC -->|JSON| AXIOS
  ORDER_SVC -->|JSON| AXIOS
  PAYMENT_SVC -->|JSON| AXIOS
  SHOP_SVC -->|JSON| AXIOS
  SHIPPING_SVC -->|JSON| AXIOS

  COMPONENTS_FEATURES -->|upload image| UTIL_CLOUDINARY
  UTIL_CLOUDINARY -->|URL| COMPONENTS_FEATURES
  UTIL_CLOUDINARY -->|to API| AXIOS

  HOOK_PAYMENT --> SOLANA
  HOOK_PAYMENT --> VNPAY
  SOLANA -->|callback| ROUTES
  VNPAY -->|callback| ROUTES

  %% Click Events
  click INDEX "https://github.com/dustopia1203/hhm-fe/blob/develop/index.html"
  click MAIN "https://github.com/dustopia1203/hhm-fe/blob/develop/src/main.tsx"
  click ROUTE_MANIFEST "https://github.com/dustopia1203/hhm-fe/blob/develop/src/routeTree.gen.ts"
  click ROUTES "https://github.com/dustopia1203/hhm-fe/tree/develop/src/routes"
  click COMPONENTS_COMMON "https://github.com/dustopia1203/hhm-fe/tree/develop/src/components/common"
  click COMPONENTS_FEATURES "https://github.com/dustopia1203/hhm-fe/tree/develop/src/components/features"
  click COMPONENTS_UI "https://github.com/dustopia1203/hhm-fe/tree/develop/src/components/ui"
  click AXIOS "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/axiosClient.ts"
  click HOOK_ACCOUNT "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/useAccountApis.ts"
  click HOOK_CATEGORY "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/useCategoryApis.ts"
  click HOOK_PRODUCT "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/useProductApis.ts"
  click HOOK_REVIEW "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/useReviewApis.ts"
  click HOOK_CART "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/useCartApis.ts"
  click HOOK_ORDER "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/useOrderApis.ts"
  click HOOK_PAYMENT "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/usePaymentApis.ts"
  click HOOK_SHOP "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/useShopApis.ts"
  click HOOK_SHIPPING "https://github.com/dustopia1203/hhm-fe/blob/develop/src/apis/useShippingApis.ts"
  click STORE_PROFILE "https://github.com/dustopia1203/hhm-fe/blob/develop/src/stores/useProfileStore.ts"
  click STORE_SHOP "https://github.com/dustopia1203/hhm-fe/blob/develop/src/stores/useShopStore.ts"
  click UTIL_AUTH "https://github.com/dustopia1203/hhm-fe/blob/develop/src/utils/auth.ts"
  click UTIL_CLOUDINARY "https://github.com/dustopia1203/hhm-fe/blob/develop/src/utils/cloudinary.ts"
  click UTIL_SEARCH "https://github.com/dustopia1203/hhm-fe/blob/develop/src/utils/searchUtils.ts"

  %% Styles
  classDef frontend fill:#E8F0FE,stroke:#1A73E8,color:#1A73E8;
  classDef api fill:#E3FCEF,stroke:#34A853,color:#34A853;
  classDef backend fill:#FCE8E6,stroke:#EA4335,color:#EA4335;
  classDef external fill:#FFF4E5,stroke:#FBBC05,color:#FBBC05;
```
