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. Feature Scope
4. UX Best Practices
5. Technical Stack
6. Implementation Roadmap
7. API Requirements
8. Performance Targets

---

Architecture Overview

Hybrid Plugin Architecture

woonoow/
├── admin-spa/              # Admin interface (existing)
├── customer-spa/           # Customer frontend (NEW)
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Shop/           # Product listing
│   │   │   ├── Product/        # Product detail
│   │   │   ├── Cart/           # Shopping cart
│   │   │   ├── Checkout/       # Checkout process
│   │   │   ├── Account/        # My Account dashboard
│   │   │   └── Orders/         # Order history
│   │   ├── components/
│   │   │   ├── ProductCard/
│   │   │   ├── CartDrawer/
│   │   │   ├── CheckoutForm/
│   │   │   └── AddressForm/
│   │   └── lib/
│   │       ├── api/
│   │       ├── cart/           # Cart state management
│   │       └── checkout/       # Checkout logic
│   └── public/
├── includes/
│   ├── Admin/
│   └── Frontend/
│       ├── Shortcodes/         # [woonoow_cart], [woonoow_checkout]
│       ├── SPA/                # Full SPA mode handler
│       └── Api/                # Customer API endpoints
└── woonoow.php

---

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

---

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.