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](#architecture-overview)
2. [Deployment Modes](#deployment-modes)
3. [SEO Strategy](#seo-strategy)
4. [Tracking & Analytics](#tracking--analytics)
5. [Feature Scope](#feature-scope)
6. [UX Best Practices](#ux-best-practices)
7. [Technical Stack](#technical-stack)
8. [Implementation Roadmap](#implementation-roadmap)
9. [API Requirements](#api-requirements)
10. [Performance Targets](#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:**
```php
// 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:**
```php
// 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
<?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:**
```jsx
// 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:**
```typescript
// 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:**
```tsx
// 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.