WooNooW/docs/CUSTOMER_SPA_ARCHITECTURE.md

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
2. Deployment Modes
3. Routing Strategy: HashRouter
4. SEO & Tracking Strategy
5. UI/UX Design Standards
6. 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.

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

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.

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