# WooNooW Customer SPA Architecture & Master Plan

**Version:** 2.0.0  
**Status:** Production Ready

This document consolidates the architectural decisions, deployment modes, UI/UX standards, and routing strategies for the WooNooW Customer SPA. It is the single source of truth for frontend development on the customer-facing side.

---

## 📋 Table of Contents

1. [Architecture Decision: Hybrid Approach](#architecture-decision-hybrid-approach)
2. [Deployment Modes](#deployment-modes)
3. [Routing Strategy: HashRouter](#routing-strategy-hashrouter)
4. [SEO & Tracking Strategy](#seo--tracking-strategy)
5. [UI/UX Design Standards](#uiux-design-standards)
6. [Implementation Roadmap](#implementation-roadmap)

---

## 1. Architecture Decision: Hybrid Approach

We previously debated whether the `customer-spa` should be built into the core plugin or sold as a separate standalone theme.

**The Decision: Option C (Hybrid Approach)**

We build the Customer SPA into the WooNooW core plugin alongside the Admin SPA.
```text
woonoow/
├── admin-spa/              (Admin interface ONLY)
├── customer-spa/           (Customer Storefront + My Account)
└── includes/
    ├── Admin/              (Backend logic for admin-spa)
    └── Frontend/           (Backend logic for customer-spa)
```

**Benefits:**
- Better user experience (one product to install).
- Highest revenue potential (core plugin covers 60% of users, premium themes can be sold separately for agencies).
- Maximum flexibility.

---

## 2. Deployment Modes

To accommodate all store owners (from small businesses using traditional themes to enterprises wanting App-like experiences), the Customer SPA supports flexible deployment:

### Mode 1: Shortcode Mode (Default / Recommended)
**Use Case:** Works with ANY WordPress theme (Divi, Elementor, Flatsome).
**How it works:** Basic components are injected via shortcodes (`[woonoow_cart]`, `[woonoow_checkout]`). 
**Benefit:** Zero theme conflicts, progressive enhancement.

### Mode 2: Full SPA Mode
**Use Case:** Maximum performance, standalone app-like experience.
**How it works:** WooNooW takes over the entire frontend routing via a dedicated settings toggle.
**Benefit:** Offline PWA support, fastest page transitions.

### Mode 3: Hybrid Rendering
**Use Case:** Best of both worlds for SEO and speed.
**How it works:** Product/Category pages use traditional WordPress PHP templates (SSR) for robust SEO, while Cart/Checkout/MyAccount use full SPA rendering for interactivity.

---

## 3. Routing Strategy: HashRouter

Direct SPA URLs (like `https://woonoow.local/product/foo`) conflict heavily with WordPress's native rewrite rules. We cannot reliably override WordPress routing without breaking standard themes or SEO canonicals.

**The Solution: HashRouter for SPA interactions**

```text
https://woonoow.local/shop#/product/edukasi-anak
                          ↑
```

### Why HashRouter?
- **Zero WordPress Conflicts:** WordPress loads the base `/shop` page template. React Router takes over everything after the `#`. 
- **Direct Access Works:** Users can bookmark or share the URL, and it will load flawlessly.
- **Consistent with Admin SPA:** Both Admin and Customer SPAs utilize memory/hash routing to prevent 404s and permalink crashes.

*(Note: For strict SEO product pages in Hybrid mode, the actual WooCommerce Product URL is indexed, while internal SPA browsing uses the HashRouter).*

---

## 4. SEO & Tracking Strategy

### Hybrid SEO Compatibility
Because pure SPAs hurt SEO (empty HTML sent to crawler), we utilize Hybrid Rendering:
1. **Product Pages = SSR:** WordPress outputs full HTML with schema markup using standard hooks so Yoast / RankMath work perfectly.
2. **Checkout/Cart = CSR:** These pages don't need SEO indexing, so they are pure React.

### Analytics Tracking
To ensure compatibility with Google Analytics, PixelMySite, Facebook Pixel, etc., the React components **trigger standard WooCommerce jQuery events**.

```javascript
// Example: Triggering a native woo event inside React
jQuery(document.body).trigger('added_to_cart', [product.id, quantity, product.price]);
```
This guarantees that 3rd-party tracking plugins installed on the site continue to function out-of-the-box without requiring custom API webhooks for the storefront.

---

## 5. UI/UX Design Standards

Our frontend philosophy: **Pragmatic, not dogmatic.** Follow e-commerce conventions for learned behaviors (e.g. swiping), rely on UX research when conventions are broken, and prioritize mobile-first performance.

### Core Layout Rules
- **Typography:** Hierarchy is `Title > Price`. We optimize for Brand Stores, not chaotic Marketplaces.
- **Variation Selectors:** Use Pills/Buttons. **Never** use Dropdowns for variation selection (high friction).
- **Product Information:** Use Vertical Accordions instead of Horizontal Tabs (27% of users overlook horizontal tabs).
- **Images:** 
  - Mobile: Use dots (learned behavior from Amazon/Tokopedia).
  - Desktop: Use small horizontal thumbnails below the main image.

### Buy Section Hierarchy
1. Product Title (H1)
2. Price & Sale formatting 
3. Stock Status Badge
4. Variation Selectors (Pills)
5. Quantity Spinner
6. **Add to Cart (Primary CTA)**
7. Trust Badges (Shipping, Returns)

---

## 6. Implementation Roadmap

### Phase 1: Core Commerce (MVP)
- Basic Product listing / catalog with filters.
- Shopping Cart sidebar/drawer (state managed by Zustand).
- Single-page checkout (HashRouter).
- My Account dashboard (React Router).

### Phase 2: Trust & Conversion
- Wishlist / Save for later functionality.
- Product reviews integration with WooCommerce comments.
- Related Products and Cross-Sells carousels.

### Phase 3: Advanced
- Subscriptions & Memberships UI.
- Digital Downloads manager in My Account.
- Progressive Web App (PWA) manifest generation and offline Service Worker.