WooNooW/SETUP_WIZARD_DESIGN.md

Setup Wizard Design Document

Overview

A guided onboarding experience for new WooNooW stores, helping merchants configure essential settings in 5-10 minutes.

Goals

1. Fast Setup - Get store operational in < 10 minutes
2. Smart Defaults - Pre-configure based on location/industry
3. Progressive - Can skip and complete later
4. Educational - Teach key concepts without overwhelming

---

Wizard Flow (5 Steps)

Step 1: Store Basics (2 min)

Purpose: Essential store identity

Fields:

• Store name (required)
• Store email (required)
• Country (required) → Auto-detects currency, timezone
• Industry (optional) → Suggests products/categories

Smart Defaults:

• Currency from country
• Timezone from country
• Language from browser

Skip: ❌ Cannot skip (required for operation)

---

Step 2: Payments (2 min)

Purpose: Enable at least one payment method

Options:

1. Quick Start (Recommended)

   • Enable manual methods (Bank Transfer, COD)
   • "Set up Stripe later" button

2. Connect Payment Provider

   • Stripe (OAuth flow)
   • PayPal (OAuth flow)
   • Other providers

Smart Defaults:

• Bank Transfer: Enabled
• Cash on Delivery: Enabled if physical products

Skip: ⚠️ Warning: "Customers won't be able to checkout"

---

Step 3: Shipping (2 min)

Purpose: Configure basic shipping

Options:

1. Simple Shipping

   • Flat rate for domestic
   • Flat rate for international
   • Free shipping threshold (optional)

2. Advanced Setup

   • Multiple zones
   • Calculated rates
   • Carrier integrations

Smart Defaults:

• Domestic zone: Country from Step 1
• Flat rate: $10 (or currency equivalent)

Skip: ⚠️ Warning: "Only for digital products"

---

Step 4: Taxes (1 min)

Purpose: Basic tax compliance

Options:

1. Auto-calculate (Recommended)

   • Based on customer location
   • Standard rates from database

2. Manual rates

   • Set fixed percentage
   • Per-country rates

3. No taxes

   • For tax-exempt stores

Smart Defaults:

• Auto-calculate: ON
• Tax rate from country (e.g., 10% for Indonesia VAT)

Skip: ✅ Can skip (configure later)

---

Step 5: First Product (3 min)

Purpose: Create sample product to test checkout

Options:

1. Create Sample Product (Recommended)

   • Pre-filled with dummy data
   • Can edit or delete later
   • Helps test checkout flow

2. Import Products

   • CSV upload
   • WooCommerce import

3. Skip for now

   • Add products later

Smart Defaults:

• Sample product based on industry from Step 1

Skip: ✅ Can skip

---

Technical Architecture

Frontend Components

/routes/Setup/
├── index.tsx           # Wizard container
├── StepProgress.tsx    # Progress indicator (1/5, 2/5, etc)
├── steps/
│   ├── StoreBasics.tsx
│   ├── Payments.tsx
│   ├── Shipping.tsx
│   ├── Taxes.tsx
│   └── FirstProduct.tsx
└── Complete.tsx        # Success screen

Backend API

// REST API Endpoints
POST /woonoow/v1/setup/store-basics
POST /woonoow/v1/setup/payments
POST /woonoow/v1/setup/shipping
POST /woonoow/v1/setup/taxes
POST /woonoow/v1/setup/first-product
POST /woonoow/v1/setup/complete

// Option to track wizard state
update_option('wnw_setup_completed', true);
update_option('wnw_setup_step', 3); // Current step

State Management

// Zustand store for wizard state
interface SetupState {
  currentStep: number;
  completed: boolean;
  data: {
    storeBasics: StoreBasicsData;
    payments: PaymentsData;
    shipping: ShippingData;
    taxes: TaxesData;
    firstProduct: ProductData;
  };
  goToStep: (step: number) => void;
  saveStep: (step: string, data: any) => Promise<void>;
  completeSetup: () => Promise<void>;
}

---

Payment Provider Integration

Architecture

Problem: How to support payment addons (Stripe, PayPal, Xendit, Midtrans, etc)?

Solution: WordPress filter hooks + React components

Backend: Payment Provider Registry

<?php
// includes/Compat/PaymentProviderRegistry.php

class PaymentProviderRegistry {
    
    /**
     * Get all registered payment providers
     * Allows addons to register their providers
     */
    public static function get_providers(): array {
        $providers = [
            // Built-in manual methods
            [
                'id' => 'bacs',
                'name' => 'Bank Transfer (BACS)',
                'type' => 'manual',
                'enabled' => true,
                'icon' => 'banknote',
            ],
            [
                'id' => 'cod',
                'name' => 'Cash on Delivery',
                'type' => 'manual',
                'enabled' => true,
                'icon' => 'banknote',
            ],
        ];
        
        /**
         * Filter: Allow addons to register payment providers
         * 
         * @param array $providers List of payment providers
         * 
         * Example addon usage:
         * add_filter('woonoow_payment_providers', function($providers) {
         *     $providers[] = [
         *         'id' => 'stripe',
         *         'name' => 'Stripe Payments',
         *         'type' => 'gateway',
         *         'description' => 'Accept Visa, Mastercard, Amex',
         *         'icon' => 'credit-card',
         *         'enabled' => false,
         *         'connected' => false,
         *         'setup_url' => admin_url('admin.php?page=wc-settings&tab=checkout&section=stripe'),
         *         'component_url' => plugins_url('build/stripe-settings.js', __FILE__),
         *         'fees' => '2.9% + $0.30 per transaction',
         *     ];
         *     return $providers;
         * });
         */
        return apply_filters('woonoow_payment_providers', $providers);
    }
    
    /**
     * Get provider configuration
     */
    public static function get_provider_config(string $provider_id): array {
        $providers = self::get_providers();
        foreach ($providers as $provider) {
            if ($provider['id'] === $provider_id) {
                return $provider;
            }
        }
        return [];
    }
    
    /**
     * Save provider settings
     */
    public static function save_provider_settings(string $provider_id, array $settings): bool {
        // Save to WooCommerce payment gateway settings
        $gateway = WC()->payment_gateways()->payment_gateways()[$provider_id] ?? null;
        if ($gateway) {
            foreach ($settings as $key => $value) {
                $gateway->update_option($key, $value);
            }
            return true;
        }
        return false;
    }
}

REST API Endpoint

<?php
// includes/API/PaymentsController.php

class PaymentsController {
    
    public static function register_routes() {
        register_rest_route('woonoow/v1', '/payments/providers', [
            'methods' => 'GET',
            'callback' => [self::class, 'get_providers'],
            'permission_callback' => [self::class, 'check_permission'],
        ]);
        
        register_rest_route('woonoow/v1', '/payments/providers/(?P<id>[a-zA-Z0-9_-]+)', [
            'methods' => 'POST',
            'callback' => [self::class, 'save_provider'],
            'permission_callback' => [self::class, 'check_permission'],
        ]);
    }
    
    public static function get_providers(WP_REST_Request $request) {
        $providers = PaymentProviderRegistry::get_providers();
        return rest_ensure_response($providers);
    }
    
    public static function save_provider(WP_REST_Request $request) {
        $provider_id = $request->get_param('id');
        $settings = $request->get_json_params();
        
        $success = PaymentProviderRegistry::save_provider_settings($provider_id, $settings);
        
        if ($success) {
            return rest_ensure_response(['success' => true]);
        }
        
        return new WP_Error('save_failed', 'Failed to save provider settings', ['status' => 500]);
    }
}

Frontend: Dynamic Provider Loading

// src/routes/Settings/Payments.tsx

import { useQuery } from '@tanstack/react-query';
import { api } from '@/lib/api';

export default function PaymentsPage() {
  // Fetch providers from API (includes addon providers)
  const { data: providers = [], isLoading } = useQuery({
    queryKey: ['payment-providers'],
    queryFn: () => api.get('/payments/providers'),
  });
  
  return (
    <SettingsLayout title="Payments">
      {/* Manual Methods */}
      <SettingsCard title="Manual Payment Methods">
        {providers
          .filter(p => p.type === 'manual')
          .map(provider => (
            <PaymentMethodCard key={provider.id} provider={provider} />
          ))}
      </SettingsCard>
      
      {/* Payment Gateways */}
      <SettingsCard title="Payment Providers">
        {providers
          .filter(p => p.type === 'gateway')
          .map(provider => (
            <PaymentProviderCard key={provider.id} provider={provider} />
          ))}
      </SettingsCard>
    </SettingsLayout>
  );
}

Addon Example: Stripe Integration

<?php
/**
 * Plugin Name: WooNooW Stripe Addon
 * Description: Stripe payment gateway for WooNooW
 */

// Register Stripe provider
add_filter('woonoow_payment_providers', function($providers) {
    $stripe_settings = get_option('woocommerce_stripe_settings', []);
    
    $providers[] = [
        'id' => 'stripe',
        'name' => 'Stripe Payments',
        'type' => 'gateway',
        'description' => 'Accept Visa, Mastercard, Amex, and more',
        'icon' => 'credit-card',
        'enabled' => $stripe_settings['enabled'] === 'yes',
        'connected' => !empty($stripe_settings['publishable_key']),
        'setup_url' => admin_url('admin.php?page=wc-settings&tab=checkout&section=stripe'),
        'component_url' => plugins_url('build/stripe-settings.js', __FILE__),
        'fees' => '2.9% + $0.30 per transaction',
        'test_mode' => $stripe_settings['testmode'] === 'yes',
    ];
    
    return $providers;
});

---

Shipping Methods Integration

Backend: Shipping Method Registry

<?php
// includes/Compat/ShippingMethodRegistry.php

class ShippingMethodRegistry {
    
    /**
     * Get all shipping zones with methods
     * Allows addons to register custom shipping methods
     */
    public static function get_zones(): array {
        $zones_data = [];
        $zones = WC_Shipping_Zones::get_zones();
        
        foreach ($zones as $zone) {
            $zone_obj = new WC_Shipping_Zone($zone['id']);
            $methods = $zone_obj->get_shipping_methods();
            
            $zone_methods = [];
            foreach ($methods as $method) {
                $zone_methods[] = [
                    'id' => $method->id,
                    'instance_id' => $method->instance_id,
                    'title' => $method->title,
                    'enabled' => $method->enabled === 'yes',
                    'method_id' => $method->id,
                    'settings' => $method->instance_settings,
                ];
            }
            
            $zones_data[] = [
                'id' => $zone['id'],
                'name' => $zone['zone_name'],
                'regions' => $zone['formatted_zone_location'],
                'methods' => $zone_methods,
            ];
        }
        
        /**
         * Filter: Allow addons to modify shipping zones
         * 
         * @param array $zones_data List of shipping zones with methods
         * 
         * Example addon usage:
         * add_filter('woonoow_shipping_zones', function($zones) {
         *     // Add custom shipping method to each zone
         *     foreach ($zones as &$zone) {
         *         $zone['methods'][] = [
         *             'id' => 'custom_shipping',
         *             'title' => 'Custom Shipping',
         *             'enabled' => true,
         *             'component_url' => plugins_url('build/custom-shipping.js', __FILE__),
         *         ];
         *     }
         *     return $zones;
         * });
         */
        return apply_filters('woonoow_shipping_zones', $zones_data);
    }
    
    /**
     * Get available shipping methods (for adding to zones)
     */
    public static function get_available_methods(): array {
        $wc_methods = WC()->shipping()->get_shipping_methods();
        $methods = [];
        
        foreach ($wc_methods as $method) {
            $methods[] = [
                'id' => $method->id,
                'title' => $method->method_title,
                'description' => $method->method_description,
            ];
        }
        
        /**
         * Filter: Allow addons to register custom shipping methods
         */
        return apply_filters('woonoow_available_shipping_methods', $methods);
    }
}

REST API Endpoint

<?php
// includes/API/ShippingController.php

class ShippingController {
    
    public static function register_routes() {
        register_rest_route('woonoow/v1', '/shipping/zones', [
            'methods' => 'GET',
            'callback' => [self::class, 'get_zones'],
            'permission_callback' => [self::class, 'check_permission'],
        ]);
        
        register_rest_route('woonoow/v1', '/shipping/methods', [
            'methods' => 'GET',
            'callback' => [self::class, 'get_methods'],
            'permission_callback' => [self::class, 'check_permission'],
        ]);
    }
    
    public static function get_zones(WP_REST_Request $request) {
        $zones = ShippingMethodRegistry::get_zones();
        return rest_ensure_response($zones);
    }
    
    public static function get_methods(WP_REST_Request $request) {
        $methods = ShippingMethodRegistry::get_available_methods();
        return rest_ensure_response($methods);
    }
}

Frontend: Dynamic Shipping Loading

// src/routes/Settings/Shipping.tsx

import { useQuery } from '@tanstack/react-query';
import { api } from '@/lib/api';

export default function ShippingPage() {
  // Fetch zones from API (includes addon methods)
  const { data: zones = [], isLoading } = useQuery({
    queryKey: ['shipping-zones'],
    queryFn: () => api.get('/shipping/zones'),
  });
  
  return (
    <SettingsLayout title="Shipping & Delivery">
      {/* Shipping Zones */}
      <SettingsCard title="Shipping Zones">
        {zones.map(zone => (
          <ShippingZoneCard key={zone.id} zone={zone} />
        ))}
      </SettingsCard>
    </SettingsLayout>
  );
}

---

Implementation Timeline

Phase 1: Foundation (Week 1)

• Create PaymentProviderRegistry.php
• Create ShippingMethodRegistry.php
• Add REST API endpoints
• Update Payments.tsx to use API
• Update Shipping.tsx to use API

Phase 2: Setup Wizard (Week 2)

• Create wizard UI components
• Implement 5-step flow
• Add smart defaults
• Add skip logic
• Create completion screen

Phase 3: Addon Support (Week 3)

• Document filter hooks
• Create example addons
• Test with real payment gateways
• Test with shipping plugins

Phase 4: Polish (Week 4)

• Add animations/transitions
• Improve error handling
• Add help documentation
• User testing & feedback

---

Success Metrics

1. Setup Time - < 10 minutes average
2. Completion Rate - > 80% complete wizard
3. Payment Setup - > 90% enable at least one method
4. Shipping Setup - > 70% configure shipping
5. First Sale - < 24 hours after setup

---

Future Enhancements

1. AI-Powered Suggestions

   • Detect industry from store name
   • Suggest products based on industry
   • Recommend payment methods by country

2. Video Tutorials

   • Embedded help videos
   • Step-by-step guides

3. Templates

   • Pre-configured setups by industry
   • "Fashion Store", "Digital Products", etc.

4. Import Wizards

   • Import from Shopify
   • Import from WooCommerce
   • Import from CSV

---

Questions & Answers

Q: How do payment addons register themselves?

A: Use the woonoow_payment_providers filter hook to add providers to the list. The addon provides metadata (name, icon, fees) and optionally a React component URL for custom settings UI.

Q: Can addons have custom settings UI?

A: Yes! Addons can provide a component_url that points to a React component. WooNooW will dynamically load and render it in the settings page.

Q: How does the wizard handle incomplete setup?

A: The wizard saves progress at each step. Users can exit and resume later. A dashboard banner reminds them to complete setup.

Q: Can merchants skip the wizard?

A: Yes, but they'll see a persistent banner until they complete essential steps (store basics, at least one payment method).

Q: How do we handle payment gateway OAuth flows?

A: Payment addons provide a setup_url that can be an OAuth redirect. After completion, the addon updates its connection status via the API.