WooNooW/CUSTOMER_SPA_MASTER_PLAN.md

Customer SPA Master Plan

WooNooW Frontend Architecture & Implementation Strategy

Version: 1.0
Date: November 21, 2025
Status: Planning Phase

---

Executive Summary

This document outlines the comprehensive strategy for building WooNooW's customer-facing SPA, including architecture decisions, deployment modes, UX best practices, and implementation roadmap.

Key Decisions

✅ Hybrid Architecture - Plugin includes customer-spa with flexible deployment modes
✅ Progressive Enhancement - Works with any theme, optional full SPA mode
✅ Mobile-First PWA - Fast, app-like experience on all devices
✅ SEO-Friendly - Server-side rendering for product pages, SPA for interactions

---

Table of Contents

1. Architecture Overview
2. Deployment Modes
3. SEO Strategy
4. Tracking & Analytics
5. Feature Scope
6. UX Best Practices
7. Technical Stack
8. Implementation Roadmap
9. API Requirements
10. Performance Targets

---

Architecture Overview

Hybrid Plugin Architecture

woonoow/
├── admin-spa/              # Admin interface ONLY
│   ├── src/
│   │   ├── routes/         # Admin pages (Dashboard, Products, Orders)
│   │   └── components/     # Admin components
│   └── public/
│
├── customer-spa/           # Customer frontend ONLY (Storefront + My Account)
│   ├── src/
│   │   ├── pages/          # Customer pages
│   │   │   ├── Shop/           # Product listing
│   │   │   ├── Product/        # Product detail
│   │   │   ├── Cart/           # Shopping cart
│   │   │   ├── Checkout/       # Checkout process
│   │   │   └── Account/        # My Account (orders, profile, addresses)
│   │   ├── components/
│   │   │   ├── ProductCard/
│   │   │   ├── CartDrawer/
│   │   │   ├── CheckoutForm/
│   │   │   └── AddressForm/
│   │   └── lib/
│   │       ├── api/            # API client
│   │       ├── cart/           # Cart state management
│   │       ├── checkout/       # Checkout logic
│   │       └── tracking/       # Analytics & pixel tracking
│   └── public/
│
└── includes/
    ├── Admin/              # Admin backend (serves admin-spa)
    │   ├── AdminController.php
    │   └── MenuManager.php
    │
    └── Frontend/           # Customer backend (serves customer-spa)
        ├── ShortcodeManager.php    # [woonoow_cart], [woonoow_checkout]
        ├── SpaManager.php          # Full SPA mode handler
        └── Api/                    # Customer API endpoints
            ├── ShopController.php
            ├── CartController.php
            └── CheckoutController.php

Key Points:

• ✅ admin-spa/ - Admin interface only
• ✅ customer-spa/ - Storefront + My Account in one app
• ✅ includes/Admin/ - Admin backend logic
• ✅ includes/Frontend/ - Customer backend logic
• ✅ Clear separation of concerns

---

Deployment Modes

Mode 1: Shortcode Mode (Default) ⭐ RECOMMENDED

Use Case: Works with ANY WordPress theme

How it works:

// In theme template or page builder
[woonoow_shop]
[woonoow_cart]
[woonoow_checkout]
[woonoow_account]

Benefits:

• ✅ Compatible with all themes
• ✅ Works with page builders (Elementor, Divi, etc.)
• ✅ Progressive enhancement
• ✅ SEO-friendly (SSR for products)
• ✅ Easy migration from WooCommerce

Architecture:

• Theme provides layout/header/footer
• WooNooW provides interactive components
• Hybrid SSR + SPA islands pattern

---

Mode 2: Full SPA Mode

Use Case: Maximum performance, app-like experience

How it works:

// Settings > Frontend > Mode: Full SPA
// WooNooW takes over entire frontend

Benefits:

• ✅ Fastest performance
• ✅ Smooth page transitions
• ✅ Offline support (PWA)
• ✅ App-like experience
• ✅ Optimized for mobile

Architecture:

• Single-page application
• Client-side routing
• Theme provides minimal wrapper
• API-driven data fetching

---

Mode 3: Hybrid Mode

Use Case: Best of both worlds

How it works:

• Product pages: SSR (SEO)
• Cart/Checkout: SPA (UX)
• My Account: SPA (performance)

Benefits:

• ✅ SEO for product pages
• ✅ Fast interactions for cart/checkout
• ✅ Balanced approach
• ✅ Flexible deployment

---

SEO Strategy

Hybrid Rendering for SEO Compatibility

Problem: Full SPA can hurt SEO because search engines see empty HTML.

Solution: Hybrid rendering - SSR for SEO-critical pages, CSR for interactive pages.

Rendering Strategy

┌─────────────────────┬──────────────┬─────────────────┐
│ Page Type           │ Rendering    │ SEO Needed?     │
├─────────────────────┼──────────────┼─────────────────┤
│ Product Listing     │ SSR          │ ✅ Yes          │
│ Product Detail      │ SSR          │ ✅ Yes          │
│ Category Pages      │ SSR          │ ✅ Yes          │
│ Search Results      │ SSR          │ ✅ Yes          │
│ Cart                │ CSR (SPA)    │ ❌ No           │
│ Checkout            │ CSR (SPA)    │ ❌ No           │
│ My Account          │ CSR (SPA)    │ ❌ No           │
│ Order Confirmation  │ CSR (SPA)    │ ❌ No           │
└─────────────────────┴──────────────┴─────────────────┘

How SSR Works

Product Page Example:

<?php
// WordPress renders full HTML (SEO-friendly)
get_header();

$product = wc_get_product( get_the_ID() );
?>

<!-- Server-rendered HTML for SEO -->
<div id="woonoow-product" data-product-id="<?php echo $product->get_id(); ?>">
  <h1><?php echo $product->get_name(); ?></h1>
  <div class="price"><?php echo $product->get_price_html(); ?></div>
  <div class="description"><?php echo $product->get_description(); ?></div>
  
  <!-- SEO plugins inject meta tags here -->
  <?php do_action('woocommerce_after_single_product'); ?>
</div>

<?php
get_footer();
// React hydrates this div for interactivity (add to cart, variations, etc.)
?>

Benefits:

• ✅ Yoast SEO works - sees full HTML
• ✅ RankMath works - sees full HTML
• ✅ Google crawls full content
• ✅ Social sharing shows correct meta tags
• ✅ React adds interactivity after page load

SEO Plugin Compatibility

Supported SEO Plugins:

• ✅ Yoast SEO
• ✅ RankMath
• ✅ All in One SEO
• ✅ SEOPress
• ✅ The SEO Framework

How it works:

1. WordPress renders product page with full HTML
2. SEO plugin injects meta tags, schema markup
3. React hydrates for interactivity
4. Search engines see complete, SEO-optimized HTML

---

Tracking & Analytics

Full Compatibility with Tracking Plugins

Goal: Ensure all tracking plugins work seamlessly with customer-spa.

Strategy: Trigger WooCommerce Events

Key Insight: Keep WooCommerce classes and trigger WooCommerce events so tracking plugins can listen.

Supported Tracking Plugins

✅ PixelMySite - Facebook, TikTok, Pinterest pixels
✅ Google Analytics - GA4, Universal Analytics
✅ Google Tag Manager - Full dataLayer support
✅ Facebook Pixel - Standard events
✅ TikTok Pixel - E-commerce events
✅ Pinterest Tag - Conversion tracking
✅ Snapchat Pixel - E-commerce events

Implementation

1. Keep WooCommerce Classes:

// customer-spa components use WooCommerce classes
<button 
  className="single_add_to_cart_button"  // WooCommerce class
  data-product_id="123"                   // WooCommerce data attr
  onClick={handleAddToCart}
>
  Add to Cart
</button>

2. Trigger WooCommerce Events:

// customer-spa/src/lib/tracking.ts

export const trackAddToCart = (product: Product, quantity: number) => {
  // 1. WooCommerce event (for PixelMySite and other plugins)
  jQuery(document.body).trigger('added_to_cart', [
    product.id,
    quantity,
    product.price
  ]);
  
  // 2. Google Analytics / GTM
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'add_to_cart',
    ecommerce: {
      items: [{
        item_id: product.id,
        item_name: product.name,
        price: product.price,
        quantity: quantity
      }]
    }
  });
  
  // 3. Facebook Pixel (if loaded by plugin)
  if (typeof fbq !== 'undefined') {
    fbq('track', 'AddToCart', {
      content_ids: [product.id],
      content_name: product.name,
      value: product.price * quantity,
      currency: 'USD'
    });
  }
};

export const trackBeginCheckout = (cart: Cart) => {
  // WooCommerce event
  jQuery(document.body).trigger('wc_checkout_loaded');
  
  // Google Analytics
  window.dataLayer?.push({
    event: 'begin_checkout',
    ecommerce: {
      items: cart.items.map(item => ({
        item_id: item.product_id,
        item_name: item.name,
        price: item.price,
        quantity: item.quantity
      }))
    }
  });
};

export const trackPurchase = (order: Order) => {
  // WooCommerce event
  jQuery(document.body).trigger('wc_order_completed', [
    order.id,
    order.total
  ]);
  
  // Google Analytics
  window.dataLayer?.push({
    event: 'purchase',
    ecommerce: {
      transaction_id: order.id,
      value: order.total,
      currency: order.currency,
      items: order.items.map(item => ({
        item_id: item.product_id,
        item_name: item.name,
        price: item.price,
        quantity: item.quantity
      }))
    }
  });
};

3. Usage in Components:

// customer-spa/src/pages/Product/AddToCartButton.tsx

import { trackAddToCart } from '@/lib/tracking';

function AddToCartButton({ product }: Props) {
  const handleClick = async () => {
    // Add to cart via API
    await cartApi.add(product.id, quantity);
    
    // Track event (triggers all pixels)
    trackAddToCart(product, quantity);
    
    // Show success message
    toast.success('Added to cart!');
  };
  
  return (
    <button 
      className="single_add_to_cart_button"
      onClick={handleClick}
    >
      Add to Cart
    </button>
  );
}

E-commerce Events Tracked

✅ View Product
✅ Add to Cart
✅ Remove from Cart
✅ View Cart
✅ Begin Checkout
✅ Add Shipping Info
✅ Add Payment Info
✅ Purchase
✅ Refund

Result

All tracking plugins work out of the box!

• PixelMySite listens to WooCommerce events ✅
• Google Analytics receives dataLayer events ✅
• Facebook/TikTok pixels fire correctly ✅
• Store owner doesn't need to change anything ✅

---

Feature Scope

Phase 1: Core Commerce (MVP)

1. Product Catalog

• Product listing with filters
• Product detail page
• Product search
• Category navigation
• Product variations
• Image gallery with zoom
• Related products

2. Shopping Cart

• Add to cart (AJAX)
• Cart drawer/sidebar
• Update quantities
• Remove items
• Apply coupons
• Shipping calculator
• Cart persistence (localStorage)

3. Checkout

• Single-page checkout
• Guest checkout
• Address autocomplete
• Shipping method selection
• Payment method selection
• Order review
• Order confirmation

4. My Account

• Dashboard overview
• Order history
• Order details
• Download invoices
• Track shipments
• Edit profile
• Change password
• Manage addresses
• Payment methods

---

Phase 2: Enhanced Features

5. Wishlist

• Add to wishlist
• Wishlist page
• Share wishlist
• Move to cart

6. Product Reviews

• Write review
• Upload photos
• Rating system
• Review moderation
• Helpful votes

7. Quick View

• Product quick view modal
• Add to cart from quick view
• Variation selection

8. Product Compare

• Add to compare
• Compare table
• Side-by-side comparison

---

Phase 3: Advanced Features

9. Subscriptions

• Subscription products
• Manage subscriptions
• Pause/resume
• Change frequency
• Update payment method

10. Memberships

• Member-only products
• Member pricing
• Membership dashboard
• Access control

11. Digital Downloads

• Download manager
• License keys
• Version updates
• Download limits

---

UX Best Practices

Research-Backed Patterns

Based on Baymard Institute research and industry leaders:

Cart UX

✅ Persistent cart drawer - Always accessible, slides from right
✅ Mini cart preview - Show items without leaving page
✅ Free shipping threshold - "Add $X more for free shipping"
✅ Save for later - Move items to wishlist
✅ Stock indicators - "Only 3 left in stock"
✅ Estimated delivery - Show delivery date

Checkout UX

✅ Progress indicator - Show steps (Shipping → Payment → Review)
✅ Guest checkout - Don't force account creation
✅ Address autocomplete - Google Places API
✅ Inline validation - Real-time error messages
✅ Trust signals - Security badges, SSL indicators
✅ Mobile-optimized - Large touch targets, numeric keyboards
✅ One-page checkout - Minimize steps
✅ Save payment methods - For returning customers

Product Page UX

✅ High-quality images - Multiple angles, zoom
✅ Clear CTA - Prominent "Add to Cart" button
✅ Stock status - In stock / Out of stock / Pre-order
✅ Shipping info - Delivery estimate
✅ Size guide - For apparel
✅ Social proof - Reviews, ratings
✅ Related products - Cross-sell

---

Technical Stack

Frontend

• Framework: React 18 (with Suspense, Transitions)
• Routing: React Router v6
• State: Zustand (cart, checkout state)
• Data Fetching: TanStack Query (React Query)
• Forms: React Hook Form + Zod validation
• Styling: TailwindCSS + shadcn/ui
• Build: Vite
• PWA: Workbox (service worker)

Backend

• API: WordPress REST API (custom endpoints)
• Authentication: WordPress nonces + JWT (optional)
• Session: WooCommerce session handler
• Cache: Transients API + Object cache

Performance

• Code Splitting: Route-based lazy loading
• Image Optimization: WebP, lazy loading, blur placeholders
• Caching: Service worker, API response cache
• CDN: Static assets on CDN

---

Implementation Roadmap

Sprint 1-2: Foundation (2 weeks)

• Setup customer-spa build system
• Create base layout components
• Implement routing
• Setup API client
• Cart state management
• Authentication flow

Sprint 3-4: Product Catalog (2 weeks)

• Product listing page
• Product filters
• Product search
• Product detail page
• Product variations
• Image gallery

Sprint 5-6: Cart & Checkout (2 weeks)

• Cart drawer component
• Cart page
• Checkout form
• Address autocomplete
• Shipping calculator
• Payment integration

Sprint 7-8: My Account (2 weeks)

• Account dashboard
• Order history
• Order details
• Profile management
• Address book
• Download manager

Sprint 9-10: Polish & Testing (2 weeks)

• Mobile optimization
• Performance tuning
• Accessibility audit
• Browser testing
• User testing
• Bug fixes

---

API Requirements

New Endpoints Needed

GET    /woonoow/v1/shop/products
GET    /woonoow/v1/shop/products/:id
GET    /woonoow/v1/shop/categories
GET    /woonoow/v1/shop/search

POST   /woonoow/v1/cart/add
POST   /woonoow/v1/cart/update
POST   /woonoow/v1/cart/remove
GET    /woonoow/v1/cart
POST   /woonoow/v1/cart/apply-coupon

POST   /woonoow/v1/checkout/calculate
POST   /woonoow/v1/checkout/create-order
GET    /woonoow/v1/checkout/payment-methods
GET    /woonoow/v1/checkout/shipping-methods

GET    /woonoow/v1/account/orders
GET    /woonoow/v1/account/orders/:id
GET    /woonoow/v1/account/downloads
POST   /woonoow/v1/account/profile
POST   /woonoow/v1/account/password
POST   /woonoow/v1/account/addresses

---

Performance Targets

Core Web Vitals

• LCP (Largest Contentful Paint): < 2.5s
• FID (First Input Delay): < 100ms
• CLS (Cumulative Layout Shift): < 0.1

Bundle Sizes

• Initial JS: < 150KB (gzipped)
• Initial CSS: < 50KB (gzipped)
• Route chunks: < 50KB each (gzipped)

Page Load Times

• Product page: < 1.5s (3G)
• Cart page: < 1s
• Checkout page: < 1.5s

---

Settings & Configuration

Frontend Settings Panel

WooNooW > Settings > Frontend
├── Mode
│   ○ Disabled (use theme)
│   ● Shortcodes (default)
│   ○ Full SPA
├── Features
│   ☑ Product catalog
│   ☑ Shopping cart
│   ☑ Checkout
│   ☑ My Account
│   ☐ Wishlist (Phase 2)
│   ☐ Product reviews (Phase 2)
├── Performance
│   ☑ Enable PWA
│   ☑ Offline mode
│   ☑ Image lazy loading
│   Cache duration: 1 hour
└── Customization
    Primary color: #000000
    Font family: System
    Border radius: 8px

---

Migration Strategy

From WooCommerce Default

1. Install WooNooW - Keep WooCommerce active
2. Enable Shortcode Mode - Test on staging
3. Replace pages - Cart, Checkout, My Account
4. Test thoroughly - All user flows
5. Go live - Switch DNS
6. Monitor - Analytics, errors

Rollback Plan

• Keep WooCommerce pages as backup
• Settings toggle to disable customer-spa
• Fallback to WooCommerce templates

---

Success Metrics

Business Metrics

• Cart abandonment rate: < 60% (industry avg: 70%)
• Checkout completion rate: > 40%
• Mobile conversion rate: > 2%
• Page load time: < 2s

Technical Metrics

• Lighthouse score: > 90
• Core Web Vitals: All green
• Error rate: < 0.1%
• API response time: < 200ms

---

Competitive Analysis

Shopify Hydrogen

• Pros: Fast, modern, React-based
• Cons: Shopify-only, complex setup
• Lesson: Simplify developer experience

WooCommerce Blocks

• Pros: Native WooCommerce integration
• Cons: Limited customization, slow
• Lesson: Provide flexibility

SureCart

• Pros: Simple, fast checkout
• Cons: Limited features
• Lesson: Focus on core experience first

---

Next Steps

1. ✅ Review and approve this plan
2. ⏳ Create detailed technical specs
3. ⏳ Setup customer-spa project structure
4. ⏳ Begin Sprint 1 (Foundation)

---

Decision Required: Approve this plan to proceed with implementation.