# arevy/shopx-frontend architecture

> Architecture diagram of the GitHub repository arevy/shopx-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arevy/shopx-frontend
- Repository: https://github.com/arevy/shopx-frontend

## Overview

##### Project Type and Purpose
- This is a full-stack e-commerce **frontend** application (“ShopX Frontend”), built with Next.js 14 (App Router), React 18, TypeScript, MobX, and GraphQL.
- It provides the customer-facing storefront: CMS-driven homepage, product catalog, cart & wishlist workflows, authentication, and checkout.
- It relies on an external GraphQL API (`e-commerce-backend`) backed by Oracle + Redis.

##### High-Level Components
a. Client–Server Runtime (Next.js)
- Server-Side Rendering (SSR)/Static Generation (SSG) on the Node.js host (port 3100)
- Client-side hydration and routing in the browser
b. Presentation Layer (React Components)
- `/src/app` – File-based routes (login, register, cart, checkout, CMS pages, products, wishlist)
- `/src/components` – Reusable UI widgets (home sections, product cards, layout, buttons, toasts)
c. State & Data Layer (MobX + GraphQL)
- `/src/stores` – MobX stores (rootStore + domain stores: cartStore, cmsStore, productStore, userStore, wishlistStore, uiStore)
- `/src/graphql/operations.ts` – Centralized GraphQL queries & mutations
- `/src/lib/graphqlClient.ts` – GraphQL client setup (endpoint configuration via NEXT_PUBLIC_GRAPHQL_ENDPOINT)
d. Static & Styles
- `/public` – Static assets
- `/src/styles` – SCSS design tokens & mixins
e. Build & Deployment
- `Dockerfile` – Multi-stage production build
- `next.config.mjs`, `tsconfig.json`, `.env.example` – Configuration

##### External Services
- GraphQL Backend (`http://localhost:4000/graphql`)
- Oracle DB + Redis caching
- Browser / End User

##### Relationships & Data Flow
1. User opens a URL → Next.js server SSR/SSG (routes under `/src/app`)
2. Next.js returns an HTML shell + initial JSON data
3. Browser hydrates React components
4. Components call MobX stores via `useStores()`
5. Stores invoke GraphQL client → send queries/mutations to external GraphQL API
6. API responds → stores update → React re-renders
7. LocalStorage sync for guest cart/wishlist, automatic migration on login

##### Architectural Patterns & Principles
- File-based routing (Next.js App Router) with per-route `page.tsx`
- Clear separation: Presentation (components) vs. State/Business logic (stores) vs. Data Access (graphqlClient)
- Single source of GraphQL operations → easier versioning & codegen
- MobX observable stores for simplified state management & reactivity
- Environment-driven config (`NEXT_PUBLIC_*` vars exposed to browser)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global entities
    User("End User"):::external
    Browser("Browser"):::external
    NodeServer("Next.js Server\n(SSR/SSG on port 3100)"):::frontend

    %% Frontend Application Container
    subgraph "ShopX Frontend App"
        direction TB

        subgraph "Routes / Pages"
            direction TB
            Layout["layout.tsx"]:::routes
            HomePageRoute["page.tsx"]:::routes
            LoginRoute["auth/login/page.tsx"]:::routes
            RegisterRoute["auth/register/page.tsx"]:::routes
            CartRoute["cart/page.tsx"]:::routes
            CheckoutRoute["checkout/page.tsx"]:::routes
            CMSRoute["cms/[slug]/page.tsx"]:::routes
            ProductsRoute["products/page.tsx"]:::routes
            ProductDetailRoute["products/[id]/page.tsx"]:::routes
            WishlistRoute["wishlist/page.tsx"]:::routes
        end

        subgraph "UI Components"
            direction TB
            HomePageComp["HomePage.tsx"]:::components
            ProductListingComp["ProductListingPage.tsx"]:::components
            ProductCard["ProductCard.tsx"]:::components
            CartPageComp["CartPage.tsx"]:::components
            CheckoutPageComp["CheckoutPage.tsx"]:::components
            WishlistPageComp["WishlistPage.tsx"]:::components
            HeaderComp["Header.tsx"]:::components
            FooterComp["Footer.tsx"]:::components
            ButtonComp["ui/Button.tsx"]:::components
            ToastStackComp["ui/ToastStack.tsx"]:::components
        end

        subgraph "Styles & Assets"
            direction TB
            Tokens["_tokens.scss"]:::styles
            Mixins["_mixins.scss"]:::styles
            StaticAssets["public/"]:::styles
        end
    end

    %% State & Data Layer
    subgraph "State & Data Layer"
        direction TB
        subgraph "MobX Stores"
            direction TB
            RootStore["rootStore.ts"]:::store
            CartStore["cartStore.ts"]:::store
            WishlistStore["wishlistStore.ts"]:::store
            UserStore["userStore.ts"]:::store
            CMSStore["cmsStore.ts"]:::store
            ProductStore["productStore.ts"]:::store
            UIStore["uiStore.ts"]:::store
        end
        GraphQLClient["graphqlClient.ts"]:::data
        Operations["operations.ts"]:::data
    end

    %% External Service
    ExternalService(["External GraphQL API\n(http://localhost:4000/graphql)"]):::externalService

    %% Connections
    User -->|"navigates"| Browser
    Browser -->|"HTTP request"| NodeServer
    NodeServer -->|"SSR/SSG"| Layout
    Layout --> HomePageRoute
    Layout --> LoginRoute
    Layout --> RegisterRoute
    Layout --> CartRoute
    Layout --> CheckoutRoute
    Layout --> CMSRoute
    Layout --> ProductsRoute
    Layout --> ProductDetailRoute
    Layout --> WishlistRoute

    HomePageRoute -->|renders| HomePageComp
    HomePageRoute -->|renders| HeaderComp
    HomePageRoute -->|renders| FooterComp

    ProductsRoute -->|renders| ProductListingComp
    ProductListingComp -->|uses| ProductCard

    CartRoute -->|renders| CartPageComp
    CheckoutRoute -->|renders| CheckoutPageComp
    WishlistRoute -->|renders| WishlistPageComp

    %% Hydration and client-side
    Browser -->|"hydrates"| HomePageComp
    HomePageComp -->|"useStores()"| RootStore
    ProductListingComp -->|"useStores()"| RootStore
    CartPageComp -->|"useStores()"| RootStore

    %% Stores to GraphQL
    RootStore -->|delegates| CartStore
    RootStore -->|delegates| WishlistStore
    RootStore -->|delegates| UserStore
    RootStore -->|delegates| CMSStore
    RootStore -->|delegates| ProductStore
    RootStore -->|delegates| UIStore

    CartStore -->|"query/mutation"| GraphQLClient
    WishlistStore -->|"query/mutation"| GraphQLClient
    UserStore -->|"query/mutation"| GraphQLClient
    CMSStore -->|"query/mutation"| GraphQLClient
    ProductStore -->|"query/mutation"| GraphQLClient

    GraphQLClient -->|"HTTP POST (GraphQL)"| ExternalService
    ExternalService -->|"response"| CartStore
    ExternalService -->|"response"| WishlistStore
    ExternalService -->|"response"| UserStore
    ExternalService -->|"response"| CMSStore
    ExternalService -->|"response"| ProductStore

    %% Data stores
    CartStore -->|"sync"| LocalStorage["LocalStorage\n(guest cart/wishlist)"]:::dataStore
    WishlistStore --> LocalStorage

    %% Click Events
    click Layout "https://github.com/arevy/shopx-frontend/blob/master/src/app/layout.tsx"
    click HomePageRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/page.tsx"
    click LoginRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/auth/login/page.tsx"
    click RegisterRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/auth/register/page.tsx"
    click CartRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/cart/page.tsx"
    click CheckoutRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/checkout/page.tsx"
    click CMSRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/cms/[slug]/page.tsx"
    click ProductsRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/products/page.tsx"
    click ProductDetailRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/products/[id]/page.tsx"
    click WishlistRoute "https://github.com/arevy/shopx-frontend/blob/master/src/app/wishlist/page.tsx"

    click HomePageComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/home/HomePage.tsx"
    click ProductListingComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/products/ProductListingPage.tsx"
    click ProductCard "https://github.com/arevy/shopx-frontend/blob/master/src/components/products/ProductCard.tsx"
    click CartPageComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/cart/CartPage.tsx"
    click CheckoutPageComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/checkout/CheckoutPage.tsx"
    click WishlistPageComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/wishlist/WishlistPage.tsx"
    click HeaderComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/layout/Header.tsx"
    click FooterComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/layout/Footer.tsx"
    click ButtonComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/ui/Button.tsx"
    click ToastStackComp "https://github.com/arevy/shopx-frontend/blob/master/src/components/ui/ToastStack.tsx"

    click RootStore "https://github.com/arevy/shopx-frontend/blob/master/src/stores/rootStore.ts"
    click CartStore "https://github.com/arevy/shopx-frontend/blob/master/src/stores/cartStore.ts"
    click WishlistStore "https://github.com/arevy/shopx-frontend/blob/master/src/stores/wishlistStore.ts"
    click UserStore "https://github.com/arevy/shopx-frontend/blob/master/src/stores/userStore.ts"
    click CMSStore "https://github.com/arevy/shopx-frontend/blob/master/src/stores/cmsStore.ts"
    click ProductStore "https://github.com/arevy/shopx-frontend/blob/master/src/stores/productStore.ts"
    click UIStore "https://github.com/arevy/shopx-frontend/blob/master/src/stores/uiStore.ts"
    click GraphQLClient "https://github.com/arevy/shopx-frontend/blob/master/src/lib/graphqlClient.ts"
    click Operations "https://github.com/arevy/shopx-frontend/blob/master/src/graphql/operations.ts"

    click Tokens "https://github.com/arevy/shopx-frontend/blob/master/src/styles/_tokens.scss"
    click Mixins "https://github.com/arevy/shopx-frontend/blob/master/src/styles/_mixins.scss"
    click StaticAssets "https://github.com/arevy/shopx-frontend/tree/master/public/"

    click GraphQLClient "https://github.com/arevy/shopx-frontend/blob/master/src/lib/graphqlClient.ts"
    click Operations "https://github.com/arevy/shopx-frontend/blob/master/src/graphql/operations.ts"

    click Dockerfile "https://github.com/arevy/shopx-frontend/tree/master/Dockerfile"
    click NextConfig "https://github.com/arevy/shopx-frontend/blob/master/next.config.mjs"
    click TSConfig "https://github.com/arevy/shopx-frontend/blob/master/tsconfig.json"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef routes fill:#B3E5FC,stroke:#0277BD,stroke-width:1px
    classDef components fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px
    classDef styles fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef store fill:#C8E6C9,stroke:#1B5E20,stroke-width:1px,stroke-dasharray: 5 5
    classDef data fill:#FFF9C4,stroke:#F57F17,stroke-width:1px
    classDef dataStore fill:#FFECB3,stroke:#FF6F00,stroke-width:1px,stroke-dasharray: 2 2
    classDef externalService fill:#FFE0B2,stroke:#E65100,stroke-width:1px
    classDef external fill:#F3E5F5,stroke:#4A148C,stroke-width:1px
```
