# 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 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.  
- **Packaging:** Composer + NPM build pipeline, `package‑zip.mjs` for release automation.  
- **Hosting:** Fully WordPress‑native, deployable on any WP host (LocalWP, Coolify, etc).

---

## 5. 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.

---