orion/docs/implementation/email-templates-architecture.md

# Email System Enhancements - Implementation Plan

## Overview

Enhance the email system to support:
- Platform-level templates with vendor overrides
- Wizamart branding by default (removed for Enterprise whitelabel tier)
- Platform-only templates that cannot be overridden
- Admin UI for editing platform templates
- 4-language support (en, fr, de, lb)
- Smart language resolution (customer → vendor → platform default)

---

## Phase 1: Database & Model Foundation

### 1.1 Update EmailTemplate Model

**File:** `models/database/email.py`

Add columns:
- `is_platform_only: bool = False` - Cannot be overridden by vendors
- `required_variables: JSON` - List of variables that must be provided

```python
is_platform_only = Column(Boolean, default=False, nullable=False)
required_variables = Column(JSON, default=list)
```

### 1.2 Create VendorEmailTemplate Model

**File:** `models/database/vendor_email_template.py`

```python
class VendorEmailTemplate(Base):
    __tablename__ = "vendor_email_templates"

    id: int
    vendor_id: int (FK → vendors.id)
    template_code: str  # References EmailTemplate.code
    language: str       # en, fr, de, lb
    subject: str
    body_html: str
    body_text: str
    is_active: bool = True
    created_at: datetime
    updated_at: datetime

    # Unique constraint: (vendor_id, template_code, language)
```

### 1.3 Migration

**File:** `alembic/versions/xxx_add_vendor_email_templates.py`

- Add columns to email_templates table
- Create vendor_email_templates table
- Add indexes for lookup performance

---

## Phase 2: Email Service Enhancement

### 2.1 Language Resolution

**Priority order for customer-facing emails:**
1. `customer.preferred_language` (if customer exists)
2. `vendor.storefront_language`
3. Platform default (`en`)

**Priority order for vendor-facing emails:**
1. `vendor.preferred_language`
2. Platform default (`en`)

### 2.2 Template Resolution

**File:** `app/services/email_service.py`

```python
def resolve_template(
    self,
    template_code: str,
    language: str,
    vendor_id: int | None = None
) -> tuple[str, str, str]:  # subject, body_html, body_text
    """
    Resolve template with vendor override support.

    1. If vendor_id provided and template not platform-only:
       - Look for VendorEmailTemplate override
       - Fall back to platform EmailTemplate
    2. If no vendor or platform-only:
       - Use platform EmailTemplate
    3. Language fallback: requested → en
    """
```

### 2.3 Branding Resolution

```python
def get_branding(self, vendor_id: int | None) -> dict:
    """
    Get branding variables for email.

    Returns:
        - platform_name: "Wizamart" or vendor.name (if whitelabel)
        - platform_logo: Wizamart logo or vendor logo (if whitelabel)
        - support_email: platform or vendor support email
        - vendor_name: Always vendor.name
        - vendor_logo: Always vendor logo
    """
    if vendor_id:
        vendor = self._get_vendor(vendor_id)
        if has_feature(vendor, "white_label"):
            return {
                "platform_name": vendor.name,
                "platform_logo": vendor.logo_url,
                ...
            }
    return {
        "platform_name": "Wizamart",
        "platform_logo": PLATFORM_LOGO_URL,
        ...
    }
```

---

## Phase 3: Admin API & UI

### 3.1 Admin API Endpoints

**File:** `app/api/v1/admin/email_templates.py`

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/email-templates` | List all platform templates |
| GET | `/email-templates/{code}` | Get template (all languages) |
| PUT | `/email-templates/{code}/{language}` | Update template |
| POST | `/email-templates/{code}/preview` | Preview with sample data |
| POST | `/email-templates/{code}/test` | Send test email |

### 3.2 Admin UI

**File:** `app/templates/admin/email-templates.html`

Features:
- List view with template codes, categories, language badges
- Edit view with:
  - Language tabs (en, fr, de, lb)
  - Subject field
  - Rich text editor for body_html
  - Plain text preview for body_text
  - Variable reference panel
  - Preview pane
  - Test send button
- Platform-only badge/indicator
- Required variables display

---

## Phase 4: Vendor API & UI

### 4.1 Vendor API Endpoints

**File:** `app/api/v1/vendor/email_templates.py`

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/email-templates` | List overridable templates |
| GET | `/email-templates/{code}` | Get vendor override or default |
| PUT | `/email-templates/{code}/{language}` | Create/update override |
| DELETE | `/email-templates/{code}/{language}` | Reset to platform default |
| POST | `/email-templates/{code}/preview` | Preview with vendor branding |
| POST | `/email-templates/{code}/test` | Send test email |

### 4.2 Vendor UI

**File:** `app/templates/vendor/email-templates.html`

Features:
- List view with templates, showing "Customized" vs "Using Default"
- Edit view similar to admin but:
  - Can only edit non-platform-only templates
  - "Reset to Default" button
  - Shows platform default as reference
- Tier gating: Only accessible for Business+ tiers

---

## Phase 5: Missing Templates

### Platform-Only Templates (Billing/Subscription)

| Code | Category | Description |
|------|----------|-------------|
| `tier_upgrade` | BILLING | Vendor upgraded subscription |
| `tier_downgrade` | BILLING | Vendor downgraded subscription |
| `payment_failed` | BILLING | Subscription payment failed |
| `subscription_cancelled` | BILLING | Subscription cancelled |
| `trial_ending` | BILLING | Trial period ending soon |
| `usage_limit_warning` | BILLING | Approaching usage limits |

### Overridable Templates

| Code | Category | Description |
|------|----------|-------------|
| `team_invite` | AUTH | Team member invitation |
| `order_shipped` | ORDERS | Order has shipped |
| `shipping_update` | ORDERS | Shipping status update |
| `low_stock_alert` | SYSTEM | Low inventory warning |

---

## Language Support Matrix

| Language | Code | Platform Default |
|----------|------|------------------|
| English | `en` | Yes (fallback) |
| French | `fr` | No |
| German | `de` | No |
| Luxembourgish | `lb` | No |

**Fallback Logic:**
```
requested_language → en (if template not found)
```

---

## Files to Create/Modify

### Phase 1 (Database)
| File | Action |
|------|--------|
| `alembic/versions/xxx_add_vendor_email_templates.py` | Create |
| `models/database/email.py` | Modify |
| `models/database/vendor_email_template.py` | Create |
| `models/database/__init__.py` | Modify |
| `models/schema/email.py` | Create |

### Phase 2 (Service)
| File | Action |
|------|--------|
| `app/services/email_service.py` | Modify |

### Phase 3 (Admin)
| File | Action |
|------|--------|
| `app/api/v1/admin/email_templates.py` | Create |
| `app/api/v1/admin/__init__.py` | Modify |
| `app/templates/admin/email-templates.html` | Create |
| `app/routes/admin_pages.py` | Modify |
| `static/admin/js/email-templates.js` | Create |

### Phase 4 (Vendor)
| File | Action |
|------|--------|
| `app/api/v1/vendor/email_templates.py` | Create |
| `app/api/v1/vendor/__init__.py` | Modify |
| `app/templates/vendor/email-templates.html` | Create |
| `app/routes/vendor_pages.py` | Modify |
| `static/vendor/js/email-templates.js` | Create |

### Phase 5 (Templates)
| File | Action |
|------|--------|
| `scripts/seed_email_templates.py` | Modify |

---

## Execution Order

1. **Phase 1**: Database migration and models (~30 min)
2. **Phase 2**: Email service enhancement (~45 min)
3. **Phase 3**: Admin API and UI (~1-2 hours)
4. **Phase 4**: Vendor API and UI (~1-2 hours)
5. **Phase 5**: Add missing templates (~30 min)
6. **Testing**: Integration tests for all phases

---

## Security Considerations

1. **XSS Prevention**: Sanitize HTML in templates before storage
2. **Access Control**: Vendors can only edit their own templates
3. **Platform-only Protection**: API enforces is_platform_only flag
4. **Template Validation**: Ensure required variables are present in template
5. **Rate Limiting**: Test email sending limited to prevent abuse