WooNooW/NOTIFICATION_STRATEGY.md

# WooNooW Notification Strategy

## Philosophy

**Core Principle:** WooNooW provides the notification framework and email as the default channel. Additional channels (WhatsApp, Telegram, SMS, etc.) are provided by addons.

---

## Architecture

### Core (WooNooW Plugin)

**Provides:**
1. **Notification Events System**
   - Order placed
   - Order status changed
   - Low stock alert
   - New customer registered
   - etc.

2. **Email Channel (Built-in)**
   - Default notification channel
   - Always available
   - Template system
   - Queue system for bulk sending

3. **Notification Settings UI**
   - Enable/disable notifications per event
   - Configure which channels to use per event
   - Template editor (for email)
   - Channel-specific settings (provided by addons)

4. **Addon Integration Points**
   - `woonoow_notification_channels` filter - Register new channels
   - `woonoow_notification_send_{channel}` action - Send via channel
   - `woonoow_notification_settings_{channel}` filter - Channel settings UI
   - `woonoow_notification_template_{channel}` filter - Channel templates

---

## Settings Page Structure

```
Notifications
├── Events (What to notify)
│   ├── Orders
│   │   ├── Order Placed
│   │   │   ├── ✓ Email (to admin)
│   │   │   ├── ✓ WhatsApp (to customer) [if addon active]
│   │   │   └── ✗ Telegram
│   │   ├── Order Completed
│   │   ├── Order Cancelled
│   │   └── Order Refunded
│   ├── Products
│   │   ├── Low Stock Alert
│   │   └── Out of Stock Alert
│   └── Customers
│       ├── New Customer
│       └── Customer Note Added
│
├── Channels (How to notify)
│   ├── Email (Built-in) ✓
│   │   ├── From Name
│   │   ├── From Email
│   │   ├── SMTP Settings (optional)
│   │   └── Templates
│   ├── WhatsApp [Addon]
│   │   ├── API Key
│   │   ├── Phone Number
│   │   └── Message Templates
│   ├── Telegram [Addon]
│   │   ├── Bot Token
│   │   ├── Chat ID
│   │   └── Message Format
│   └── SMS [Addon]
│       ├── Provider (Twilio, etc.)
│       ├── API Credentials
│       └── Message Templates
│
└── Templates
    ├── Email Templates
    ├── WhatsApp Templates [if addon active]
    └── Telegram Templates [if addon active]
```

---

## Implementation

### 1. Core Notification System

```php
// includes/Core/Notifications/NotificationManager.php
class NotificationManager {
    private $channels = [];
    
    public function register_channel($id, $label, $callback) {
        $this->channels[$id] = [
            'label' => $label,
            'callback' => $callback,
        ];
    }
    
    public function send($event, $data, $channels = ['email']) {
        foreach ($channels as $channel) {
            if (isset($this->channels[$channel])) {
                call_user_func($this->channels[$channel]['callback'], $event, $data);
            }
        }
    }
}
```

### 2. Email Channel (Built-in)

```php
// includes/Core/Notifications/Channels/EmailChannel.php
class EmailChannel {
    public static function init() {
        add_filter('woonoow_notification_channels', [__CLASS__, 'register']);
        add_action('woonoow_notification_send_email', [__CLASS__, 'send'], 10, 2);
    }
    
    public static function register($channels) {
        $channels['email'] = [
            'id' => 'email',
            'label' => 'Email',
            'icon' => 'mail',
            'builtin' => true,
        ];
        return $channels;
    }
    
    public static function send($event, $data) {
        // Send email using WooNooW mail queue
    }
}
```

### 3. Addon Example: WhatsApp Channel

```php
// woonoow-whatsapp/includes/WhatsAppChannel.php
class WhatsAppChannel {
    public static function init() {
        add_filter('woonoow_notification_channels', [__CLASS__, 'register']);
        add_action('woonoow_notification_send_whatsapp', [__CLASS__, 'send'], 10, 2);
        add_filter('woonoow_notification_settings_whatsapp', [__CLASS__, 'settings']);
    }
    
    public static function register($channels) {
        $channels['whatsapp'] = [
            'id' => 'whatsapp',
            'label' => 'WhatsApp',
            'icon' => 'message-circle',
            'addon' => 'woonoow-whatsapp',
        ];
        return $channels;
    }
    
    public static function send($event, $data) {
        // Send WhatsApp message via API
    }
    
    public static function settings() {
        return [
            'api_key' => get_option('woonoow_whatsapp_api_key'),
            'phone_number' => get_option('woonoow_whatsapp_phone'),
        ];
    }
}
```

---

## Frontend (React SPA)

### Notifications Settings Page

```tsx
// admin-spa/src/routes/Settings/Notifications.tsx

interface NotificationChannel {
  id: string;
  label: string;
  icon: string;
  builtin?: boolean;
  addon?: string;
  enabled: boolean;
}

interface NotificationEvent {
  id: string;
  label: string;
  description: string;
  category: 'orders' | 'products' | 'customers';
  channels: {
    [channelId: string]: {
      enabled: boolean;
      recipient: 'admin' | 'customer' | 'both';
    };
  };
}

export default function NotificationsPage() {
  // Fetch available channels (core + addons)
  const { data: channels } = useQuery({
    queryKey: ['notification-channels'],
    queryFn: () => api.get('/notifications/channels'),
  });
  
  // Fetch notification events configuration
  const { data: events } = useQuery({
    queryKey: ['notification-events'],
    queryFn: () => api.get('/notifications/events'),
  });
  
  return (
    <SettingsLayout title="Notifications">
      {/* Available Channels */}
      <SettingsCard title="Notification Channels">
        {channels?.map(channel => (
          <ChannelCard key={channel.id} channel={channel} />
        ))}
      </SettingsCard>
      
      {/* Events Configuration */}
      <SettingsCard title="Order Notifications">
        {events?.filter(e => e.category === 'orders').map(event => (
          <EventCard 
            key={event.id} 
            event={event} 
            channels={channels}
          />
        ))}
      </SettingsCard>
      
      {/* More categories... */}
    </SettingsLayout>
  );
}
```

---

## Benefits

1. **Extensible:** Addons can add any notification channel
2. **Flexible:** Each event can use multiple channels
3. **User-Friendly:** Clear UI showing what's available
4. **No Bloat:** Core only includes email
5. **Addon Revenue:** Premium channels (WhatsApp, SMS) can be paid addons

---

## Example Addons

### Free Addons
- **WooNooW Telegram** - Send notifications via Telegram bot
- **WooNooW Discord** - Send notifications to Discord channel

### Premium Addons
- **WooNooW WhatsApp Pro** - WhatsApp Business API integration
- **WooNooW SMS** - SMS notifications via Twilio/Nexmo
- **WooNooW Push** - Browser push notifications
- **WooNooW Slack** - Team notifications via Slack

---

## Migration Path

**Phase 1 (Current):**
- Build notification framework
- Implement email channel
- Create settings UI with addon slots

**Phase 2:**
- Build first addon (Telegram) as proof of concept
- Document addon API
- Create addon template

**Phase 3:**
- Build premium addons (WhatsApp, SMS)
- Marketplace listing
- Community addons

---

## Key Takeaway

**WooNooW Core = Framework + Email**
**Everything Else = Addons**

This keeps the core lean while providing unlimited extensibility for notification channels.