VOID Storefront Client Documentation

This document describes the codebase of the customer-facing e-commerce storefront for VOID. The application is built to deliver a premium, high-speed, and immersive brand presentation and shopping interface.

---

1. Technical Stack & Key Libraries

• Framework: Next.js v16.1.6 (App Router) & React 19.
• Styling:
  • Tailwind CSS v4 & PostCSS: Maximum styling control and modern CSS architecture.
  • Framer Motion: Powering subtle micro-animations, page transitions, and page loaders.
  • Lucide React & React Icons: Icon typography.
• WebGL / Graphics:
  • Three.js, @react-three/fiber, and @react-three/postprocessing: Renders an interactive, dithered GPU-accelerated wave shader in the homepage Hero section and load overlays (Dither.tsx).
• Form Handling & Validation:
  • React Hook Form: Handles address lists, contact details, authentication, and review forms.
  • Zod: Validation schema definitions with internationalized error mappings (zod-i18n-map).
• Localization:
  • Next-Intl: Configures path-based internationalization routing and JSON locale dictionaries.
• State Management:
  • React Context: Manages client-side states (e.g. cart drawer, themes, wishlist cache, authentication tokens).
• Notifications:
  • React Hot Toast: Action alerts and system feedback messages.

---

2. Dynamic Routing & Multi-Language Support

The application is fully localized and structured under the Next.js localized route group: /[locale].

• Supported Languages: English (en) and Arabic (ar).
• Locale Routing: Pathnames are automatically prefixed with the active locale code (e.g., voideg.com/en/shop or voideg.com/ar/shop). Language toggles instantly rewrite routes without resetting client states.
• Text Alignment (Bi-directional Layout):
  • English sets dir="ltr" and imports modern typography.
  • Arabic sets dir="rtl" and loads optimized typography.
  • Next-intl translates structural text, validation messages, and policy pages via translation files in /messages.

---

3. Page Structure & Components

A. Homepage (/[locale]/page.tsx)

Features an immersive experience through modular sections:

• Hero (Hero.tsx): Integrates the Dither canvas background with responsive mouse interaction, animated signature typographic entry ("V-O-I-D"), and call-to-actions.
• Manifesto (Manifesto.tsx): A scroll-linked interaction that fades typography in and out depending on viewport scroll progress.
• Brand Story (BrandStory.tsx): Narrates the VOID philosophy.
• Quality Features (QualityFeatures.tsx): Displays product benefits, emphasizing 100% Egyptian Cotton heavyweight fabrics (450 GSM) and boxy streetwear fits.
• Big Marquee & Visual Loop: Continuous media tickers and loop playback.

B. Catalog & Filtering (/[locale]/shop & /collections)

• Search System: Real-time keyword processing.
• Filtering System:
  • Category listings.
  • Price bounds slider (Minimum to Maximum).
  • Stock availability state (In Stock vs. Out of Stock).
  • Tag sorting filters (New Arrivals, On Sale).
• Sorting System:
  • Standard sorting filters (Newest, Oldest, Best Selling, Price Low-to-High, Price High-to-Low).

C. Product Detail Page (/[locale]/product/[slug])

• Interactive Swatches: Supports dynamic color-swatch clicks that update galleries and check stock levels.
• Inventory Feedback: Shows real-time warnings when items are low in stock (e.g. "Only 3 left in stock!").
• Size Chart & Guide: Includes a size grid chart detailing chest widths and body lengths in centimeters.
• Localized Technical Spec Accordion:
  • Clothing Specifications: Fabric compositions, GSM weight, drop-shoulder descriptions.
  • Perfume Specifications: Fragrance families and note hierarchies (top, middle, and base notes).
• Customer Reviews: Shows user ratings and reviews with options to create or edit them.

D. Cart Management (/[locale]/cart)

• A slide-over cart drawer overlay.
• Synchronizes with both local storage and database instances.
• Free Shipping Tracker: Includes a visual progress bar indicating how much more the user needs to add to unlock free shipping based on the store's settings.

E. Checkout System (/[locale]/checkout)

• Guest & Customer Checkouts: Allows users to place orders without registration.
• Geolocation auto-fill: Integrates the browser Geolocation API to fetch coordinates, assisting in auto-resolving addresses and calculating shipping fees.
• Payment Types:
  • Cash on Delivery (COD).
  • Instapay Bank Transfer: Displays QR codes and prompts the user to enter their Instapay reference number to confirm payment.

F. Order Success Tracker (/[locale]/order-success/[id])

• Displays an order confirmation page.
• Status Progress Bar: Tracks orders in real-time (Placed -> Processing -> Shipped -> Delivered -> Cancelled).
• WhatsApp API link: Generates a link to contact the courier or support directly with the order ID.

G. Customer Dashboard Profile (/[locale]/profile)

• Displays order history, delivery states, and invoices.
• Address Book Manager: Adds, deletes, and updates default delivery addresses.
• Wishlist Cache: Displays favorited items.
• Profile Edit Form: Updates profile attributes (birthdate, gender, phone).
• Self-Service Deletion: Allows users to permanently delete their account with password confirmation.

---

4. WebGL Canvas Shaders (Dither.tsx)

The platform's signature visual element is the dithered interactive background. It uses @react-three/fiber and custom shaders.

• Component: Dither.tsx
• Features:
  • Renders a plane geometry with a custom shader material that calculates waves based on sine/cosine wave functions.
  • Passes parameters: waveColor (RGB array), waveSpeed, waveAmplitude, waveFrequency, colorNum, pixelSize, and mouseRadius.
  • Captures cursor movement on the window viewport and maps pointer positions to webgl coordinate bounds, passing them as uniforms to simulate gravity waves in real-time.
  • Integrates an @react-three/postprocessing dither shader, rendering pixelated retro gradients that align with the brand's aesthetic.

---

5. Client State Management Providers

State is managed client-side using React Context Providers:

1. AuthContext
   • Properties: user (profile details, default address), token (JWT token), loading flag.
   • Methods: login(email, password), register(details), logout(), updateProfile(details).
   • Behavior: Persists user session in localStorage under void_user and adds credentials to subsequent API requests.
2. CartContext
   • Properties: cartItems (array of items with size, color, quantity), cartTotal, freeShippingProgress, isCartOpen state.
   • Methods: addItem(item), removeItem(itemId), updateQty(itemId, qty), clearCart().
   • Behavior: Synchronizes cart states with local storage and calls /api/cart to sync state with registered profiles when users are logged in.
3. ThemeContext
   • Properties: theme ("light" or "dark"), systemTheme.
   • Methods: setTheme(themeName).
   • Behavior: Integrates with Next-Themes and Tailwind v4 to update document class listings, adjusting visual palettes dynamically.

---

6. Client-Side Tracking & Analytics Pipeline

The storefront handles analytical tracking by gathering client parameters and passing them to the API backend:

1. Parameters Captured:

   • UTM campaign variables (utm_source, utm_medium, utm_campaign, utm_term, utm_content).
   • Browser user-agent and OS.
   • Screen width and device type.
   • HTTP referrers and initial landing page.
   • GA4 Client ID and Session ID.

2. Centralized Fetch Request Interceptor (apiFetch.ts): Every HTTP request generated by the storefront client to the backend API automatically appends client telemetry data via request headers:

   • Authorization: Bearer <JWT> (if logged in).
   • X-Tracking-Data: Stringified UTM query parameters, landing pages, referrers, and Google Analytics identifiers.
   • X-Device-Info: Stringified screen width, screen height, OS, and device type.
   • X-Client-Language: Local client configuration language.