How arevy/shopx-frontend works
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)