142 lines
5.8 KiB
Markdown
142 lines
5.8 KiB
Markdown
# 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.
|