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'
4.8 KiB
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:
- No Migration Needed — Woo data stays intact.
- Safe Activate/Deactivate — deactivate anytime without data loss.
- Hybrid by Default — SSR + SPA islands for cart, checkout, and my‑account.
- Full SPA Toggle — optional React‑only mode for performance‑critical sites.
- HPOS Mandatory — optimized data reads/writes with indexed datastores.
- Compat Layer — hook mirror + slot rendering for legacy addons.
- 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:
- Read WooCommerce Structure — Listen to WC's registered gateways, shipping methods, and settings (the "bone structure")
- Transform & Simplify — Convert complex WC settings into clean, categorized UI with progressive disclosure
- Enhance Performance — Direct DB operations where safe, bypassing WC bloat (30s → 1-2s like Orders)
- Respect the Ecosystem — If addon extends
WC_Payment_GatewayorWC_Shipping_Method, it appears automatically - 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.