f205027c6d
📝 Changes: - Added Phase 4.5: Settings SPA & Setup Wizard - Added Section 5: Settings Architecture Philosophy - Documented 'better wardrobe' approach - Clarified WooCommerce bone structure respect - Defined compatibility stance 🎯 Key Principles: - Read WC structure (don't create parallel system) - Transform & simplify (better UX) - Enhance performance (like Orders: 30s → 1-2s) - Respect ecosystem (auto-support WC-compliant addons) - No new hooks (listen to WC hooks) 🎨 UI Strategy: - Generic form builder (standard) - Custom components (popular gateways) - Redirect to WC (complex/non-standard) - Multi-page forms (20+ fields) Compatibility: 'If it works in WC, it works in WooNooW'
89 lines
4.8 KiB
Markdown
89 lines
4.8 KiB
Markdown
|
||
|
||
|
||
# WooNooW — Modern Experience Layer for WooCommerce
|
||
|
||
## 1. Background
|
||
|
||
WooCommerce remains the world’s most widely used e‑commerce engine, but its architecture has become increasingly heavy, fragmented, and difficult to modernize.
|
||
The transition toward React‑based components (Cart/Checkout Blocks, HPOS, and new admin screens) introduces compatibility issues that render many existing addons obsolete.
|
||
Store owners and developers face a dilemma: migrate to new SaaS‑like platforms (SureCart, NorthCommerce) and lose their data, or stay with WooCommerce and endure performance and UX stagnation.
|
||
|
||
**Key pain points:**
|
||
- Checkout performance bottlenecks and delayed responses due to synchronous PHP operations (e.g., `wp_mail`).
|
||
- Legacy admin and product interfaces causing friction for daily operations.
|
||
- HPOS transition breaking legacy addons that query `wp_posts`.
|
||
- Increasing incompatibility between modern Woo Blocks and PHP‑based extensions.
|
||
|
||
---
|
||
|
||
## 2. Vision & Solution Direction
|
||
|
||
WooNooW acts as a **modern experience layer** for WooCommerce — enhancing UX, performance, and reliability **without data migration**.
|
||
It does not replace WooCommerce; it evolves it.
|
||
By overlaying a fast React‑powered frontend and a modern admin SPA, WooNooW upgrades the store experience while keeping full backward compatibility with existing data, plugins, and gateways.
|
||
|
||
**Core principles:**
|
||
1. **No Migration Needed** — Woo data stays intact.
|
||
2. **Safe Activate/Deactivate** — deactivate anytime without data loss.
|
||
3. **Hybrid by Default** — SSR + SPA islands for cart, checkout, and my‑account.
|
||
4. **Full SPA Toggle** — optional React‑only mode for performance‑critical sites.
|
||
5. **HPOS Mandatory** — optimized data reads/writes with indexed datastores.
|
||
6. **Compat Layer** — hook mirror + slot rendering for legacy addons.
|
||
7. **Async System** — mail and heavy actions queued via Action Scheduler.
|
||
|
||
---
|
||
|
||
## 3. Development Method & Phases
|
||
|
||
| Phase | Scope | Output |
|
||
|-------|--------|--------|
|
||
| **Phase 1** | Core plugin foundation, menu, REST routes, async email | Working prototype with dashboard & REST health check |
|
||
| **Phase 2** | Checkout Fast‑Path (quote, submit), cart hybrid SPA | Fast checkout pipeline, HPOS datastore |
|
||
| **Phase 3** | Customer SPA (My Account, Orders, Addresses) | React SPA integrated with Woo REST |
|
||
| **Phase 4** | Admin SPA (Orders List, Detail, Dashboard, Standalone Mode) | React admin interface with 3 modes: normal (wp-admin), fullscreen, standalone |
|
||
| **Phase 4.5** | Settings SPA (Store, Payments, Shipping, Taxes, Checkout) | Shopify-inspired settings UI reading WooCommerce structure; Setup Wizard for onboarding |
|
||
| **Phase 5** | Compatibility Hooks & Slots | Legacy addon support maintained |
|
||
| **Phase 6** | Packaging & Licensing | Release build, Sejoli integration, and addon manager |
|
||
|
||
All development follows incremental delivery with full test coverage on REST endpoints and admin components.
|
||
|
||
---
|
||
|
||
## 4. Technical Strategy
|
||
|
||
- **Backend:** PHP 8.2+, WooCommerce HPOS, Action Scheduler, Redis (object cache).
|
||
- **Frontend:** React 18 + TypeScript, Vite, React Query, Tailwind/Radix for UI.
|
||
- **Architecture:** Modular PSR‑4 autoload, REST‑driven logic, SPA hydration islands.
|
||
- **Performance:** Read‑through cache, async queues, lazy data hydration.
|
||
- **Compat:** HookBridge and SlotRenderer ensuring PHP‑hook addons still render inside SPA.
|
||
|
||
---
|
||
|
||
## 5. Settings Architecture Philosophy
|
||
|
||
WooNooW settings act as a **"better wardrobe"** for WooCommerce configuration:
|
||
|
||
**Core Principles:**
|
||
1. **Read WooCommerce Structure** — Listen to WC's registered gateways, shipping methods, and settings (the "bone structure")
|
||
2. **Transform & Simplify** — Convert complex WC settings into clean, categorized UI with progressive disclosure
|
||
3. **Enhance Performance** — Direct DB operations where safe, bypassing WC bloat (30s → 1-2s like Orders)
|
||
4. **Respect the Ecosystem** — If addon extends `WC_Payment_Gateway` or `WC_Shipping_Method`, it appears automatically
|
||
5. **No New Hooks** — Don't ask addons to support us; we support WooCommerce's existing hooks
|
||
|
||
**UI Strategy:**
|
||
- **Generic form builder** as standard for all WC-compliant gateways/methods
|
||
- **Custom components** for recognized popular gateways (Stripe, PayPal) while respecting the standard
|
||
- **Redirect to WC settings** for complex/non-standard addons
|
||
- **Multi-page forms** for gateways with 20+ fields (categorized: Basic → API → Advanced)
|
||
|
||
**Compatibility Stance:**
|
||
> "If it works in WooCommerce, it works in WooNooW. If it doesn't respect WooCommerce's structure, we can't help."
|
||
|
||
---
|
||
|
||
## 6. Strategic Goal
|
||
|
||
Position WooNooW as the **"WooCommerce for Now"** — a paid addon that delivers the speed and UX of modern SaaS platforms while retaining the ecosystem power and self‑hosted freedom of WooCommerce.
|
||
|
||
--- |