# 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. [Feature Scope](#feature-scope)
4. [UX Best Practices](#ux-best-practices)
5. [Technical Stack](#technical-stack)
6. [Implementation Roadmap](#implementation-roadmap)
7. [API Requirements](#api-requirements)
8. [Performance Targets](#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:**
```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

---

## 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.