# WooNooW Customer SPA Architecture
## 🎯 Core Decision: Full SPA Takeover (No Hybrid)
### ❌ What We're NOT Doing (Lessons Learned)
**REJECTED: Hybrid SSR + SPA approach**
- WordPress renders HTML (SSR)
- React hydrates on top (SPA)
- WooCommerce hooks inject content
- Theme controls layout
**PROBLEMS EXPERIENCED:**
- ✗ Script loading hell (spent 3+ hours debugging)
- ✗ React Refresh preamble errors
- ✗ Cache conflicts
- ✗ Theme conflicts
- ✗ Hook compatibility nightmare
- ✗ Inconsistent UX (some pages SSR, some SPA)
- ✗ Not truly "single-page" - full page reloads
### ✅ What We're Doing Instead
**APPROVED: Full SPA Takeover**
- React controls ENTIRE page (including ``, ``)
- Zero WordPress theme involvement
- Zero WooCommerce template rendering
- Pure client-side routing
- All data via REST API
**BENEFITS:**
- ✓ Clean separation of concerns
- ✓ True SPA performance
- ✓ No script loading issues
- ✓ No theme conflicts
- ✓ Predictable behavior
- ✓ Easy to debug
---
## 🏗️ Architecture Overview
### System Diagram
```
┌─────────────────────────────────────────────────────┐
│ WooNooW Plugin │
├─────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Admin SPA │ │ Customer SPA │ │
│ │ (React) │ │ (React) │ │
│ │ │ │ │ │
│ │ - Products │ │ - Shop │ │
│ │ - Orders │ │ - Product Detail │ │
│ │ - Customers │ │ - Cart │ │
│ │ - Analytics │ │ - Checkout │ │
│ │ - Settings │◄─────┤ - My Account │ │
│ │ └─ Customer │ │ │ │
│ │ SPA Config │ │ Uses settings │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ └────────┬────────────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ REST API Layer │ │
│ │ (PHP Controllers) │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ WordPress Core │ │
│ │ + WooCommerce │ │
│ │ (Data Layer Only) │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────┘
```
---
## 🔧 Three-Mode System
### Mode 1: Admin Only (Default)
```
✅ Admin SPA: Active (product management, orders, etc.)
❌ Customer SPA: Inactive
→ User uses their own theme/page builder for frontend
```
### Mode 2: Full SPA (Complete takeover)
```
✅ Admin SPA: Active
✅ Customer SPA: Full Mode (takes over entire site)
→ WooNooW controls everything
→ Choose from 4 layouts: Classic, Modern, Boutique, Launch
```
### Mode 3: Checkout-Only SPA 🆕 (Hybrid approach)
```
✅ Admin SPA: Active
✅ Customer SPA: Checkout Mode (partial takeover)
→ Only overrides: Checkout → Thank You → My Account
→ User keeps theme/page builder for landing pages
→ Perfect for single product sellers with custom landing pages
```
**Settings UI:**
```
Admin SPA > Settings > Customer SPA
Customer SPA Mode:
○ Disabled (Use your own theme)
○ Full SPA (Take over entire storefront)
● Checkout Only (Override checkout pages only)
If Checkout Only selected:
Pages to override:
[✓] Checkout
[✓] Thank You (Order Received)
[✓] My Account
[ ] Cart (optional)
```
---
## 🔌 Technical Implementation
### 1. Customer SPA Activation Flow
```php
// When user enables Customer SPA in Admin SPA:
1. Admin SPA sends: POST /wp-json/woonoow/v1/settings/customer-spa
{
"enabled": true,
"layout": "modern",
"colors": {...},
...
}
2. PHP saves to wp_options:
update_option('woonoow_customer_spa_enabled', true);
update_option('woonoow_customer_spa_settings', $settings);
3. PHP activates template override:
- template_include filter returns spa-full-page.php
- Dequeues all theme scripts/styles
- Outputs minimal HTML with React mount point
4. React SPA loads and takes over entire page
```
### 2. Template Override (PHP)
**File:** `includes/Frontend/TemplateOverride.php`
```php
public static function use_spa_template($template) {
$mode = get_option('woonoow_customer_spa_mode', 'disabled');
// Mode 1: Disabled
if ($mode === 'disabled') {
return $template; // Use normal theme
}
// Mode 3: Checkout-Only (partial SPA)
if ($mode === 'checkout_only') {
$checkout_pages = get_option('woonoow_customer_spa_checkout_pages', [
'checkout' => true,
'thankyou' => true,
'account' => true,
'cart' => false,
]);
if (($checkout_pages['checkout'] && is_checkout()) ||
($checkout_pages['thankyou'] && is_order_received_page()) ||
($checkout_pages['account'] && is_account_page()) ||
($checkout_pages['cart'] && is_cart())) {
return plugin_dir_path(__DIR__) . '../templates/spa-full-page.php';
}
return $template; // Use theme for other pages
}
// Mode 2: Full SPA
if ($mode === 'full') {
// Override all WooCommerce pages
if (is_woocommerce() || is_cart() || is_checkout() || is_account_page()) {
return plugin_dir_path(__DIR__) . '../templates/spa-full-page.php';
}
}
return $template;
}
```
### 3. SPA Template (Minimal HTML)
**File:** `templates/spa-full-page.php`
```php
>
<?php wp_title('|', true, 'right'); ?><?php bloginfo('name'); ?>
>
```
**That's it!** No WordPress theme markup, no WooCommerce templates.
### 4. React SPA Entry Point
**File:** `customer-spa/src/main.tsx`
```typescript
import React from 'react';
import { createRoot } from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import App from './App';
import './index.css';
// Get config from PHP
const config = window.woonoowCustomer;
// Mount React app
const root = document.getElementById('woonoow-customer-app');
if (root) {
createRoot(root).render(
);
}
```
### 5. React Router (Client-Side Only)
**File:** `customer-spa/src/App.tsx`
```typescript
import { Routes, Route } from 'react-router-dom';
import { ThemeProvider } from './contexts/ThemeContext';
import Layout from './components/Layout';
import Shop from './pages/Shop';
import Product from './pages/Product';
import Cart from './pages/Cart';
import Checkout from './pages/Checkout';
import Account from './pages/Account';
export default function App({ config }) {
return (
} />
} />
} />
} />
} />
);
}
```
**Key Point:** React Router handles ALL navigation. No page reloads!
---
## 📋 Implementation Roadmap
### Phase 1: Core Infrastructure ✅ (DONE)
- [x] Full-page SPA template
- [x] Script loading (Vite dev server)
- [x] React Refresh preamble fix
- [x] Template override system
- [x] Dequeue conflicting scripts
### Phase 2: Settings System (NEXT)
- [ ] Create Settings REST API endpoint
- [ ] Build Settings UI in Admin SPA
- [ ] Implement color picker component
- [ ] Implement layout selector
- [ ] Save/load settings from wp_options
### Phase 3: Theme System
- [ ] Create 3 master layouts (Classic, Modern, Boutique)
- [ ] Implement design token system
- [ ] Build ThemeProvider
- [ ] Apply theme to all components
### Phase 4: Homepage Builder
- [ ] Create section components (Hero, Featured, etc.)
- [ ] Build drag-drop section manager
- [ ] Section configuration modals
- [ ] Dynamic section rendering
### Phase 5: Navigation
- [ ] Fetch WP menus via REST API
- [ ] Render menus in SPA
- [ ] Mobile menu component
- [ ] Mega menu support
### Phase 6: Pages
- [ ] Shop page (product grid)
- [ ] Product detail page
- [ ] Cart page
- [ ] Checkout page
- [ ] My Account pages
---
## ✅ Decision Log
| Decision | Rationale | Date |
|----------|-----------|------|
| **Full SPA takeover (no hybrid)** | Hybrid SSR+SPA caused script loading hell, cache issues, theme conflicts | Nov 22, 2024 |
| **Settings in Admin SPA (not wp-admin)** | Consistent UX, better UI components, easier to maintain | Nov 22, 2024 |
| **3 master layouts (not infinite)** | SaaS approach: curated options > infinite flexibility | Nov 22, 2024 |
| **Design tokens (not custom CSS)** | Maintainable, predictable, accessible | Nov 22, 2024 |
| **Client-side routing only** | True SPA performance, no page reloads | Nov 22, 2024 |
---
## 📚 Related Documentation
- [Customer SPA Settings](./CUSTOMER_SPA_SETTINGS.md) - Settings schema & API
- [Customer SPA Theme System](./CUSTOMER_SPA_THEME_SYSTEM.md) - Design tokens & layouts
- [Customer SPA Development](./CUSTOMER_SPA_DEVELOPMENT.md) - Dev guide for contributors