WooNooW/NOTIFICATION_SYSTEM.md

# Notification System Documentation

**Status:** ✅ Complete & Fully Wired  
**Last Updated:** November 15, 2025

---

## Overview

WooNooW features a modern, flexible notification system that supports multiple channels (Email, Push, WhatsApp, Telegram, SMS) with customizable templates and markdown support.

### Key Features
- ✅ Multi-channel support (Email, Push, + Addons)
- ✅ Custom markdown templates with visual builder
- ✅ Variable system for dynamic content
- ✅ Global system toggle (WooNooW vs WooCommerce)
- ✅ Per-channel and per-event toggles
- ✅ Email customization (colors, logo, branding)
- ✅ Async email queue (prevents 30s timeout)
- ✅ Full backend wiring complete

---

## Architecture

### Structure
```
Notifications
├── Staff Notifications (toggle channels/events)
├── Customer Notifications (toggle channels/events)
├── Channel Configuration (global settings)
│   ├── Email (template + connection)
│   └── Push (template + connection)
└── Activity Log (coming soon)
```

### Notification Flow
```
Event → EmailManager → Check System Mode → Check Channel Toggle
→ Check Event Toggle → EmailRenderer → Get Template → Replace Variables
→ Parse Markdown → Apply Branding → Queue via MailQueue → Send
```

---

## Markdown Syntax

### Cards
```markdown
[card:info]
Your content here
[/card]

[card:success]
Success message
[/card]

[card:warning]
Warning message
[/card]
```

### Buttons
```markdown
[button:solid](https://example.com)
Click Me
[/button]

[button:outline](https://example.com)
Learn More
[/button]
```

### Images
```markdown
![Alt text](https://example.com/image.png)
```

---

## Variables

### Order Variables
- `{order_number}` - Order number
- `{order_date}` - Order date
- `{order_total}` - Order total
- `{order_status}` - Order status
- `{order_items_table}` - Formatted table
- `{order_items_list}` - Formatted list

### Customer Variables
- `{customer_name}` - Customer full name
- `{customer_first_name}` - First name
- `{customer_last_name}` - Last name
- `{customer_email}` - Email address

### Store Variables
- `{store_name}` - Store name
- `{store_url}` - Store URL
- `{store_email}` - Store email

---

## Backend Integration

### API Endpoints

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/notifications/system-mode` | Get current mode |
| POST | `/notifications/system-mode` | Switch mode |
| GET | `/notifications/channels` | Get all channels |
| POST | `/notifications/channels/toggle` | Toggle channel |
| GET | `/notifications/events` | Get all events |
| POST | `/notifications/events/update` | Update event |
| GET | `/notifications/templates/{id}/{ch}` | Get template |
| POST | `/notifications/templates` | Save template |
| GET | `/notifications/email-settings` | Get email customization |
| POST | `/notifications/email-settings` | Save email customization |

### Database Options

```php
// System mode
woonoow_notification_system_mode = 'woonoow' | 'woocommerce'

// Channel toggles
woonoow_email_notifications_enabled = true | false
woonoow_push_notifications_enabled = true | false

// Event settings
woonoow_notification_settings = [
  'order_processing' => [
    'channels' => [
      'email' => ['enabled' => true, 'recipient' => 'customer']
    ]
  ]
]

// Templates
woonoow_notification_templates = [
  'order_processing_email_customer' => [
    'subject' => '...',
    'body' => '...'
  ]
]

// Email customization
woonoow_email_settings = [
  'primary_color' => '#7f54b3',
  'logo_url' => '...',
  ...
]
```

---

## Email Queue System

### Purpose
Prevents 30-second timeout when sending emails via SMTP.

### Implementation
- **WooEmailOverride**: Intercepts `wp_mail()` calls
- **MailQueue**: Queues emails via Action Scheduler
- **Async Processing**: Emails sent in background

### Files
- `includes/Core/Mail/WooEmailOverride.php`
- `includes/Core/Mail/MailQueue.php`

### Initialization
```php
// In Bootstrap.php
MailQueue::init();
WooEmailOverride::init();
```

---

## Key Classes

### NotificationManager
**File:** `includes/Core/Notifications/NotificationManager.php`

- `should_send_notification()` - Validates all toggles
- `send()` - Main sending method
- `is_channel_enabled()` - Check global channel state
- `is_event_channel_enabled()` - Check per-event state

### EmailManager
**File:** `includes/Core/Notifications/EmailManager.php`

- `is_enabled()` - Check if WooNooW system active
- `disable_wc_emails()` - Disable WooCommerce emails
- Hooks into WooCommerce order status changes

### EmailRenderer
**File:** `includes/Core/Notifications/EmailRenderer.php`

- `render()` - Render email from template
- `replace_variables()` - Replace variables with data
- `parse_cards()` - Parse markdown cards
- Applies email customization

### TemplateProvider
**File:** `includes/Core/Notifications/TemplateProvider.php`

- `get_template()` - Get custom or default template
- `get_variables()` - Get available variables
- `get_default_template()` - Get default template

---

## Global System Toggle

### Purpose
Allow users to switch between WooNooW and WooCommerce notification systems.

### Modes

**WooNooW Mode** (default):
- Custom templates with markdown
- Multi-channel support
- Full customization
- WooCommerce emails disabled

**WooCommerce Mode**:
- Standard WooCommerce emails
- WooNooW notifications disabled
- For users who prefer classic system

### Implementation
```php
// Check mode
$mode = get_option('woonoow_notification_system_mode', 'woonoow');

// EmailManager respects mode
if (!EmailManager::is_enabled()) {
    return; // Skip WooNooW notifications
}

// NotificationManager checks mode
if ($system_mode !== 'woonoow') {
    return false; // Use WooCommerce instead
}
```

---

## Q&A

### Q: Are templates saved and used when sending?
**A:** ✅ Yes. Templates saved via API are fetched by EmailRenderer and used when sending.

### Q: Are channel toggles respected?
**A:** ✅ Yes. NotificationManager checks both global and per-event toggles before sending.

### Q: Does the global system toggle work?
**A:** ✅ Yes. EmailManager and NotificationManager both check the mode before processing.

### Q: Is email sending async?
**A:** ✅ Yes. MailQueue queues emails via Action Scheduler to prevent timeouts.

### Q: Are variables replaced correctly?
**A:** ✅ Yes. EmailRenderer replaces all variables with actual data from orders/customers.

### Q: Does markdown parsing work?
**A:** ✅ Yes. Cards, buttons, and images are parsed correctly in both visual builder and email output.

---

## Related Documentation

- **NEW_MARKDOWN_SYNTAX.md** - Markdown syntax reference
- **NOTIFICATION_SYSTEM_QA.md** - Q&A and backend status
- **BACKEND_WIRING_COMPLETE.md** - Backend integration details
- **CUSTOM_EMAIL_SYSTEM.md** - Email system architecture
- **FILTER_HOOKS_GUIDE.md** - Available hooks for customization

---

## Future Enhancements

### Planned Features
- Activity Log page
- WhatsApp addon
- Telegram addon
- SMS addon
- A/B testing for templates
- Scheduled notifications
- Customer notification preferences page

### Addon Development
See **ADDON_DEVELOPMENT_GUIDE.md** for creating custom notification channels.