docs: consolidate markdown documentation into master guides and remove obsolete files
This commit is contained in:
Dwindi Ramadhana
141
docs/CUSTOMER_SPA_ARCHITECTURE.md
Normal file
141
docs/CUSTOMER_SPA_ARCHITECTURE.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user