orion/docs/frontend/shop/architecture.md

╔══════════════════════════════════════════════════════════════════╗
║         SHOP FRONTEND ARCHITECTURE OVERVIEW                      ║
║         Alpine.js + Jinja2 + Tailwind CSS + Multi-Theme          ║
╚══════════════════════════════════════════════════════════════════╝

📦 WHAT IS THIS?
═════════════════════════════════════════════════════════════════

Customer-facing shop frontend provides visitors with a branded
e-commerce experience unique to each vendor. Built with:
  ✅ Jinja2 Templates (server-side rendering)
  ✅ Alpine.js (client-side reactivity)
  ✅ Tailwind CSS (utility-first styling)
  ✅ Multi-Theme System (vendor branding)
  ✅ FastAPI (backend routes)


🎯 KEY PRINCIPLES
═════════════════════════════════════════════════════════════════

1. Theme-First Design
   • Each vendor has unique colors, fonts, logos
   • CSS variables for dynamic theming
   • Custom CSS support per vendor
   • Dark mode with vendor colors

2. Progressive Enhancement
   • Works without JavaScript (basic HTML)
   • JavaScript adds cart, search, filters
   • Graceful degradation for older browsers

3. API-First Data Loading
   • All products from REST APIs
   • Client-side cart management
   • Real-time stock updates
   • Search and filtering

4. Responsive & Mobile-First
   • Mobile-first Tailwind approach
   • Touch-friendly interactions
   • Optimized images
   • Fast page loads


📁 FILE STRUCTURE
═════════════════════════════════════════════════════════════════

app/
├── templates/shop/
│   ├── base.html                    ← ✅ Base template (layout + theme)
│   ├── home.html                    ← ✅ Homepage / featured products
│   ├── products.html                ← ✅ Product catalog with filters
│   ├── product.html                 ← Product detail page
│   ├── cart.html                    ← Shopping cart
│   ├── checkout.html                ← Checkout flow
│   ├── search.html                  ← Search results
│   ├── account/                     ← Customer account pages
│   │   ├── login.html
│   │   ├── register.html
│   │   ├── dashboard.html
│   │   ├── orders.html
│   │   ├── profile.html
│   │   └── addresses.html
│   └── errors/                      ← Error pages
│       ├── 400.html
│       ├── 404.html
│       └── 500.html
│
├── static/shop/
│   ├── css/
│   │   └── shop.css                 ← ✅ Shop-specific styles (IMPLEMENTED)
│   ├── js/
│   │   └── shop-layout.js           ← ✅ Base shop functionality (IMPLEMENTED)
│   └── img/
│       └── (placeholder images)
│
├── static/shared/                   ← ✅ Shared across all areas (IMPLEMENTED)
│   ├── js/
│   │   ├── log-config.js            ← ✅ Logging setup
│   │   ├── icons.js                 ← ✅ Icon registry
│   │   ├── utils.js                 ← ✅ Utility functions
│   │   └── api-client.js            ← ✅ API wrapper
│   └── css/
│       └── (shared styles if needed)
│
└── routes/
    └── shop_pages.py                ← ✅ Route handlers (IMPLEMENTED)


🏗️  ARCHITECTURE LAYERS
═════════════════════════════════════════════════════════════════

Layer 1: Routes (FastAPI)
  ↓
Layer 2: Middleware (Vendor + Theme Detection)
  ↓
Layer 3: Templates (Jinja2)
  ↓
Layer 4: JavaScript (Alpine.js)
  ↓
Layer 5: API (REST endpoints)
  ↓
Layer 6: Database


Layer 1: ROUTES (FastAPI)
──────────────────────────────────────────────────────────────────
Purpose: Vendor Detection + Template Rendering
Location: app/routes/shop_pages.py

Example:
  @router.get("/", response_class=HTMLResponse, include_in_schema=False)
  @router.get("/products", response_class=HTMLResponse, include_in_schema=False)
  async def shop_products_page(request: Request):
      """
      Render shop homepage / product catalog.
      Vendor and theme are auto-injected by middleware.
      """
      return templates.TemplateResponse(
          "shop/products.html",
          get_shop_context(request)  # Helper function
      )

Helper Function:
  def get_shop_context(request: Request, **extra_context) -> dict:
      """Build template context with vendor/theme from middleware"""
      vendor = getattr(request.state, 'vendor', None)
      theme = getattr(request.state, 'theme', None)
      clean_path = getattr(request.state, 'clean_path', request.url.path)
      vendor_context = getattr(request.state, 'vendor_context', None)

      # Get detection method (domain, subdomain, or path)
      access_method = vendor_context.get('detection_method', 'unknown') if vendor_context else 'unknown'

      # Calculate base URL for links
      # - Domain/subdomain: base_url = "/"
      # - Path-based: base_url = "/vendor/{vendor_code}/"
      base_url = "/"
      if access_method == "path" and vendor:
          full_prefix = vendor_context.get('full_prefix', '/vendor/')
          base_url = f"{full_prefix}{vendor.subdomain}/"

      return {
          "request": request,
          "vendor": vendor,
          "theme": theme,
          "clean_path": clean_path,
          "access_method": access_method,
          "base_url": base_url,  # ⭐ Used for all links in templates
          **extra_context
      }

Responsibilities:
  ✅ Access vendor from middleware (request.state.vendor)
  ✅ Access theme from middleware (request.state.theme)
  ✅ Calculate base_url for routing-aware links
  ✅ Render template with context
  ❌ NO database queries (data loaded client-side via API)
  ❌ NO business logic (handled by API endpoints)


⭐ MULTI-ACCESS ROUTING (Domain, Subdomain, Path-Based)
──────────────────────────────────────────────────────────────────
The shop frontend supports THREE access methods:

1. **Custom Domain** (Production)
   URL: https://customdomain.com/products
   - Vendor has their own domain
   - base_url = "/"
   - Links: /products, /about, /contact

2. **Subdomain** (Production)
   URL: https://wizamart.letzshop.com/products
   - Vendor uses platform subdomain
   - base_url = "/"
   - Links: /products, /about, /contact

3. **Path-Based** (Development/Testing)
   URL: http://localhost:8000/vendor/wizamart/products
   - Vendor accessed via path prefix
   - base_url = "/vendor/wizamart/"
   - Links: /vendor/wizamart/products, /vendor/wizamart/about

⚠️ CRITICAL: All template links MUST use {{ base_url }} prefix

Example:
  ❌ BAD:  <a href="/products">Products</a>
  ✅ GOOD: <a href="{{ base_url }}products">Products</a>

  ❌ BAD:  <a href="/contact">Contact</a>
  ✅ GOOD: <a href="{{ base_url }}contact">Contact</a>

How It Works:
  1. VendorContextMiddleware detects access method
  2. Sets request.state.vendor_context with detection_method
  3. get_shop_context() calculates base_url from detection_method
  4. Templates use {{ base_url }} for all internal links
  5. Links work correctly regardless of access method


Layer 2: MIDDLEWARE
──────────────────────────────────────────────────────────────────
Purpose: Vendor & Theme Identification

Two middleware components work together:

1. Vendor Context Middleware (middleware/vendor_context.py)
   • Detects vendor from domain/subdomain/path
   • Sets request.state.vendor
   • Sets request.state.vendor_context (includes detection_method)
   • Sets request.state.clean_path (path without vendor prefix)
   • Returns 404 if vendor not found

2. Theme Context Middleware (middleware/theme_context.py)
   • Loads theme for detected vendor
   • Sets request.state.theme
   • Falls back to default theme

Order matters:
  vendor_context_middleware → theme_context_middleware

Detection Methods:
  - custom_domain: Vendor has custom domain
  - subdomain: Vendor uses platform subdomain
  - path: Vendor accessed via /vendor/{code}/ or /vendors/{code}/


Layer 3: TEMPLATES (Jinja2)
──────────────────────────────────────────────────────────────────
Purpose: HTML Structure + Vendor Branding
Location: app/templates/shop/

Template Hierarchy:
  base.html (layout + theme injection)
    ↓
  home.html (product grid)
    ↓
  partials/product-card.html (components)

Example:
  {% extends "shop/base.html" %}
  {% block title %}{{ vendor.name }}{% endblock %}
  {% block alpine_data %}shopHome(){% endblock %}
  {% block content %}
    <div x-show="loading">Loading products...</div>
    <div x-show="!loading" class="grid grid-cols-1 md:grid-cols-4 gap-6">
      <template x-for="product in products" :key="product.id">
        <!-- Product card -->
      </template>
    </div>
  {% endblock %}

Key Features:
  ✅ Theme CSS variables injection
  ✅ Vendor logo (light/dark mode)
  ✅ Custom CSS from theme
  ✅ Social links from theme
  ✅ Dynamic favicon


Layer 4: JAVASCRIPT (Alpine.js)
──────────────────────────────────────────────────────────────────
Purpose: Client-Side Interactivity + Cart + Search
Location: app/static/shop/js/

⚠️ CRITICAL: JavaScript Loading Order
──────────────────────────────────────────────────────────────────
Scripts MUST load in this exact order (see base.html):

  1. log-config.js         ← Logging system (loads first)
  2. icons.js              ← Icon registry
  3. shop-layout.js        ← Alpine component (before Alpine!)
  4. utils.js              ← Utility functions
  5. api-client.js         ← API wrapper
  6. Alpine.js (deferred)  ← Loads last
  7. Page-specific JS      ← Optional page scripts

Why This Order Matters:
  • shop-layout.js defines shopLayoutData() BEFORE Alpine initializes
  • Alpine.js defers to ensure DOM is ready
  • Shared utilities available to all scripts
  • Icons and logging available immediately

Example from base.html:
  <script src="{{ url_for('static', path='shared/js/log-config.js') }}"></script>
  <script src="{{ url_for('static', path='shared/js/icons.js') }}"></script>
  <script src="{{ url_for('static', path='shop/js/shop-layout.js') }}"></script>
  <script src="{{ url_for('static', path='shared/js/utils.js') }}"></script>
  <script src="{{ url_for('static', path='shared/js/api-client.js') }}"></script>
  <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Alpine.js Component (shop-layout.js):
──────────────────────────────────────────────────────────────────
  function shopLayoutData() {
      return {
          // Theme state
          dark: localStorage.getItem('shop-theme') === 'dark',

          // UI state
          mobileMenuOpen: false,
          searchOpen: false,
          cartCount: 0,

          // Cart state
          cart: [],

          init() {
              shopLog.info('Shop layout initializing...');
              this.loadCart();
              window.addEventListener('cart-updated', () => {
                  this.loadCart();
              });
              shopLog.info('Shop layout initialized');
          },

          addToCart(product, quantity = 1) {
              const existingIndex = this.cart.findIndex(
                  item => item.id === product.id
              );

              if (existingIndex !== -1) {
                  this.cart[existingIndex].quantity += quantity;
              } else {
                  this.cart.push({
                      id: product.id,
                      name: product.name,
                      price: product.price,
                      image: product.image,
                      quantity: quantity
                  });
              }

              this.saveCart();
              this.showToast(`${product.name} added to cart`, 'success');
          },

          toggleTheme() {
              this.dark = !this.dark;
              localStorage.setItem('shop-theme',
                  this.dark ? 'dark' : 'light');
              shopLog.debug('Theme toggled:', this.dark ? 'dark' : 'light');
          }
      };
  }

  // Make globally available
  window.shopLayoutData = shopLayoutData;

Template Usage:
──────────────────────────────────────────────────────────────────
  {# In base.html #}
  <html x-data="shopLayoutData()" x-bind:class="{ 'dark': dark }">

  {# In page templates #}
  {% block alpine_data %}shopLayoutData(){% endblock %}

Responsibilities:
  ✅ Load products from API
  ✅ Manage cart in localStorage
  ✅ Handle search and filters
  ✅ Update DOM reactively
  ✅ Theme toggling (light/dark)
  ✅ Mobile menu management
  ✅ Toast notifications


Layer 5: API (REST)
──────────────────────────────────────────────────────────────────
Purpose: Product Data + Cart + Orders
Location: app/api/v1/shop/*.py (not pages.py)

Example Endpoints:
  GET    /api/v1/shop/{vendor_code}/products
  GET    /api/v1/shop/{vendor_code}/products/{id}
  GET    /api/v1/shop/{vendor_code}/categories
  POST   /api/v1/shop/{vendor_code}/search
  POST   /api/v1/shop/{vendor_code}/cart/checkout


🔄 DATA FLOW
═════════════════════════════════════════════════════════════════

Page Load Flow:
──────────────────────────────────────────────────────────────────
  1. Customer → visits acme-shop.com
  2. Vendor Middleware → Identifies "ACME" vendor
  3. Theme Middleware → Loads ACME's theme config
  4. FastAPI → Renders shop/home.html
  5. Browser → Receives HTML with theme CSS variables
  6. Alpine.js → init() executes
  7. JavaScript → GET /api/v1/shop/ACME/products
  8. API → Returns product list JSON
  9. Alpine.js → Updates products array
  10. Browser → DOM updates with product cards

Add to Cart Flow:
──────────────────────────────────────────────────────────────────
  1. Customer → Clicks "Add to Cart"
  2. Alpine.js → addToCart(product, quantity)
  3. Alpine.js → Updates cart array
  4. Alpine.js → Saves to localStorage
  5. Alpine.js → Updates cartCount badge
  6. Alpine.js → Shows toast notification
  7. Browser → Cart icon updates automatically

Checkout Flow:
──────────────────────────────────────────────────────────────────
  1. Customer → Goes to /cart
  2. Page → Loads cart from localStorage
  3. Customer → Fills checkout form
  4. Alpine.js → POST /api/v1/shop/ACME/cart/checkout
  5. API → Creates order + payment intent
  6. Alpine.js → Redirects to payment
  7. Payment → Completes
  8. Redirect → /order/{order_id}/confirmation


🎨 MULTI-THEME SYSTEM
═════════════════════════════════════════════════════════════════

How Themes Work:

1. Database Storage
   • Each vendor has a theme record
   • Stores colors, fonts, logos, layout prefs
   • Custom CSS per vendor

2. CSS Variables Injection
   • base.html injects variables in <style> tag
   • Variables available throughout page
   • Example:
     :root {
         --color-primary: #6366f1;
         --color-secondary: #8b5cf6;
         --color-accent: #ec4899;
         --color-background: #ffffff;
         --color-text: #1f2937;
         --font-heading: Inter, sans-serif;
         --font-body: Inter, sans-serif;
     }

3. Usage in Templates
   <button style="background-color: var(--color-primary)">
       Buy Now
   </button>

4. Dark Mode
   • Vendor colors adjust for dark mode
   • Saved in localStorage
   • Applied via :class="{ 'dark': dark }"
   • Uses dark: variants in Tailwind


Theme Configuration Example:
──────────────────────────────────────────────────────────────────
{
    "theme_name": "modern",
    "colors": {
        "primary": "#6366f1",
        "secondary": "#8b5cf6",
        "accent": "#ec4899",
        "background": "#ffffff",
        "text": "#1f2937"
    },
    "fonts": {
        "heading": "Inter, sans-serif",
        "body": "Inter, sans-serif"
    },
    "branding": {
        "logo": "/media/vendors/acme/logo.png",
        "logo_dark": "/media/vendors/acme/logo-dark.png",
        "favicon": "/media/vendors/acme/favicon.ico"
    },
    "layout": {
        "header": "fixed",
        "style": "grid"
    },
    "social_links": {
        "facebook": "https://facebook.com/acme",
        "instagram": "https://instagram.com/acme"
    },
    "custom_css": ".product-card { border-radius: 12px; }"
}


🛒 CART SYSTEM
═════════════════════════════════════════════════════════════════

Client-Side Cart Management:

Storage: localStorage
Format: JSON array of cart items

Cart Item Structure:
{
    "id": "product-123",
    "name": "Product Name",
    "price": 29.99,
    "quantity": 2,
    "image": "/media/products/image.jpg",
    "vendor_code": "ACME"
}

Key Functions:
  • loadCart(): Load from localStorage
  • saveCart(): Persist to localStorage
  • addToCart(product, quantity): Add item
  • updateCartItem(id, quantity): Update quantity
  • removeFromCart(id): Remove item
  • clearCart(): Empty cart
  • cartTotal: Computed total price

Cart Persistence:
  • Survives page refresh
  • Shared across shop pages
  • Cleared on checkout completion
  • Synced across tabs (optional)


🔍 SEARCH & FILTERS
═════════════════════════════════════════════════════════════════

Search System:

1. Search Modal
   • Overlay with input
   • Live search as you type
   • Keyboard shortcuts (Cmd+K)

2. Search API
   POST /api/v1/shop/{vendor_code}/search
   {
       "query": "laptop",
       "category": "electronics",
       "min_price": 100,
       "max_price": 1000,
       "sort": "price:asc"
   }

3. Client-Side Filtering
   • Filter products array
   • No API call needed for basic filters
   • Use for in-memory datasets

Filter Components:
  • Category dropdown
  • Price range slider
  • Sort options
  • Availability toggle
  • Brand checkboxes


📱 RESPONSIVE DESIGN
═════════════════════════════════════════════════════════════════

Breakpoints (Tailwind):
  • sm: 640px  (mobile landscape)
  • md: 768px  (tablet)
  • lg: 1024px (desktop)
  • xl: 1280px (large desktop)

Product Grid Responsive:
  • Mobile: 1 column
  • Tablet: 2 columns
  • Desktop: 4 columns

Example:
  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
    <!-- Product cards -->
  </div>

Touch Optimization:
  • Larger touch targets (min 44x44px)
  • Swipeable carousels
  • Touch-friendly buttons
  • Tap to zoom images


🌙 DARK MODE
═════════════════════════════════════════════════════════════════

Implementation:
  1. Alpine.js state: dark: boolean
  2. HTML class binding: :class="{ 'dark': dark }"
  3. Tailwind variants: dark:bg-gray-800
  4. LocalStorage persistence
  5. Vendor colors adapt to dark mode

Toggle Button:
  <button @click="toggleTheme()">
      <svg x-show="!dark"><!-- Sun icon --></svg>
      <svg x-show="dark"><!-- Moon icon --></svg>
  </button>

Dark Mode Colors:
  • Background: dark:bg-gray-900
  • Text: dark:text-gray-100
  • Borders: dark:border-gray-700
  • Cards: dark:bg-gray-800

Vendor Colors:
  • Primary color adjusts brightness
  • Maintains brand identity
  • Readable in both modes


🔐 CUSTOMER AUTHENTICATION
═════════════════════════════════════════════════════════════════

Optional Auth System:

Guest Checkout:
  ✅ No account required
  ✅ Email for order updates
  ✅ Quick checkout

Account Features:
  ✅ Order history
  ✅ Saved addresses
  ✅ Wishlist
  ✅ Profile management

Auth Flow:
  1. Login/Register → POST /api/v1/shop/auth/login
  2. API → Return JWT token
  3. JavaScript → Store in localStorage
  4. API Client → Add to authenticated requests
  5. Optional → Use account features


📡 API CLIENT
═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/api-client.js

Usage:
  const products = await apiClient.get(
      `/api/v1/shop/${vendorCode}/products`
  );
  
  const order = await apiClient.post(
      `/api/v1/shop/${vendorCode}/checkout`,
      orderData
  );

Features:
  ✅ Automatic error handling
  ✅ JSON parsing
  ✅ Loading states
  ✅ Auth token injection (if logged in)


🐛 LOGGING
═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/log-config.js

Shop-Specific Logging:
  shopLog.info('Product added to cart', product);
  shopLog.error('Checkout failed', error);
  shopLog.debug('Search query', { query, results });

Levels:
  • INFO: User actions
  • ERROR: Failures and exceptions
  • DEBUG: Development debugging
  • WARN: Warnings


🎭 ICONS
═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/icons.js

Usage:
  <span x-html="$icon('shopping-cart', 'w-5 h-5')"></span>
  <span x-html="$icon('search', 'w-6 h-6 text-primary')"></span>

Shop Icons:
  • shopping-cart, shopping-bag
  • heart (wishlist)
  • search, filter
  • eye (view)
  • star (rating)
  • truck (shipping)
  • check (success)
  • x (close)
  • chevron-left, chevron-right
  • spinner (loading)


🚀 PERFORMANCE
═════════════════════════════════════════════════════════════════

Optimization Techniques:

1. Image Optimization
   • WebP format
   • Lazy loading
   • Responsive images (srcset)
   • CDN delivery

2. Code Splitting
   • Base layout loads first
   • Page-specific JS loads after
   • Deferred non-critical CSS

3. Caching
   • Browser cache for assets
   • LocalStorage for cart
   • Service worker (optional)

4. Lazy Loading
   • Products load as you scroll
   • Images load when visible
   • Infinite scroll for large catalogs

5. CDN Assets with Fallback
   • Tailwind CSS from CDN (fallback to local)
   • Alpine.js from CDN (fallback to local)
   • Works offline and in restricted networks
   • See: [CDN Fallback Strategy](../cdn-fallback-strategy.md)


📊 PAGE-BY-PAGE BREAKDOWN
═════════════════════════════════════════════════════════════════

/ (Homepage)
──────────────────────────────────────────────────────────────────
Purpose: Display featured products, hero section
Components:
  • Hero banner with CTA
  • Featured products grid
  • Category cards
  • About vendor section
Data Sources:
  • GET /api/v1/shop/{code}/products?featured=true
  • GET /api/v1/shop/{code}/categories

/products
──────────────────────────────────────────────────────────────────
Purpose: Browse all products with filters
Components:
  • Product grid
  • Filter sidebar
  • Sort dropdown
  • Pagination
Data Sources:
  • GET /api/v1/shop/{code}/products
  • Filters applied client-side or server-side

/products/{product_id}
──────────────────────────────────────────────────────────────────
Purpose: Single product detail page
Components:
  • Image gallery
  • Product info
  • Add to cart form
  • Related products
  • Reviews (optional)
Data Sources:
  • GET /api/v1/shop/{code}/products/{id}
  • GET /api/v1/shop/{code}/products/{id}/related

/cart
──────────────────────────────────────────────────────────────────
Purpose: Review cart contents before checkout
Components:
  • Cart items list
  • Quantity adjusters
  • Remove buttons
  • Cart total
  • Checkout button
Data Sources:
  • LocalStorage cart
  • No API call needed

/checkout
──────────────────────────────────────────────────────────────────
Purpose: Complete purchase
Components:
  • Shipping form
  • Payment form
  • Order summary
  • Submit button
Data Sources:
  • POST /api/v1/shop/{code}/checkout
  • Stripe/PayPal integration

/search
──────────────────────────────────────────────────────────────────
Purpose: Search results page
Components:
  • Search input
  • Results grid
  • Filter options
  • Sort options
Data Sources:
  • POST /api/v1/shop/{code}/search

/category/{category_slug}
──────────────────────────────────────────────────────────────────
Purpose: Browse products by category
Components:
  • Breadcrumbs
  • Product grid
  • Subcategories
  • Filters
Data Sources:
  • GET /api/v1/shop/{code}/categories/{slug}/products

/about
──────────────────────────────────────────────────────────────────
Purpose: About the vendor
Components:
  • Vendor story
  • Team photos
  • Values/mission
  • Contact info
Data Sources:
  • Vendor info from middleware
  • Static content

/contact
──────────────────────────────────────────────────────────────────
Purpose: Contact form
Components:
  • Contact form
  • Map (optional)
  • Business hours
  • Social links
Data Sources:
  • POST /api/v1/shop/{code}/contact


🎓 LEARNING PATH
═════════════════════════════════════════════════════════════════

For New Developers:

1. Understand Architecture (1 hour)
   → Read this document
   → Review file structure
   → Examine base template
   → Understand theme system

2. Study Existing Page (2 hours)
   → Open home.html
   → Open shop-layout.js
   → Trace product loading flow
   → Examine cart management

3. Create Simple Page (4 hours)
   → Copy templates
   → Modify for new feature
   → Test with different vendor themes
   → Verify responsive design

4. Add Complex Feature (1 day)
   → Product filters
   → Cart operations
   → API integration
   → Search functionality

5. Master Patterns (1 week)
   → All common patterns
   → Theme customization
   → Performance optimization
   → Mobile responsiveness


🔄 DEPLOYMENT CHECKLIST
═════════════════════════════════════════════════════════════════

Before Deploying:
  □ Build Tailwind CSS
  □ Minify JavaScript
  □ Test all routes
  □ Test with multiple vendor themes
  □ Verify cart persistence
  □ Check mobile responsive
  □ Test dark mode
  □ Validate product display
  □ Test checkout flow
  □ Check image optimization
  □ Test search functionality
  □ Verify social links
  □ Test across browsers
  □ Check console for errors
  □ Test in production mode


🔒 SECURITY
═════════════════════════════════════════════════════════════════

Best Practices:

1. Input Validation
   ✅ Validate all form inputs
   ✅ Sanitize user content
   ✅ XSS prevention

2. Cart Security
   ✅ Validate cart on server
   ✅ Check stock availability
   ✅ Verify prices server-side
   ✅ Never trust client cart

3. Payment Security
   ✅ Use trusted payment providers
   ✅ Never store card details
   ✅ HTTPS only
   ✅ PCI compliance

4. Rate Limiting
   ✅ Search endpoint throttling
   ✅ Contact form limits
   ✅ Checkout attempt limits


📚 REFERENCE LINKS
═════════════════════════════════════════════════════════════════

Documentation:
  • Alpine.js: https://alpinejs.dev/
  • Tailwind CSS: https://tailwindcss.com/
  • Jinja2: https://jinja.palletsprojects.com/
  • FastAPI: https://fastapi.tiangolo.com/

Internal Docs:
  • Page Template Guide: FRONTEND_SHOP_ALPINE_PAGE_TEMPLATE.md
  • Multi-Theme Guide: MULTI_THEME_SHOP_GUIDE.md
  • API Documentation: API_REFERENCE.md
  • Database Schema: DATABASE_SCHEMA.md


══════════════════════════════════════════════════════════════════
                    SHOP FRONTEND ARCHITECTURE
         Theme-Driven, Customer-Focused, Brand-Consistent
══════════════════════════════════════════════════════════════════