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

Email Templates Architecture (Future)

Overview

Email templates follow a similar pattern to the CMS content pages system, with platform defaults that vendors can override.

Architecture

Template Hierarchy

1. Platform Default Templates - Admin-managed base templates

   • Order confirmation
   • Shipping notification
   • Password reset
   • Welcome email
   • Invoice email
   • etc.

2. Vendor Overrides - Optional customization

   • Vendors can override platform templates
   • Cannot create new template types (unlike CMS pages)
   • Must maintain required placeholders

Multi-language Support

• Each template exists in all supported languages (FR, EN, DE, LB)
• Vendor overrides are per-language
• Falls back to platform default if no vendor override

Key Differences from CMS Pages

Feature	CMS Pages	Email Templates
Create new	Vendors can create	Vendors cannot create
Template types	Unlimited	Fixed set by platform
Tier limits	Number of pages per tier	No limits (all templates available)
Override	Full content	Full content

Database Design (Proposed)

-- Platform templates (admin-managed)
CREATE TABLE email_templates (
    id SERIAL PRIMARY KEY,
    template_key VARCHAR(100) NOT NULL,  -- e.g., 'order_confirmation'
    language VARCHAR(5) NOT NULL,         -- e.g., 'fr', 'en', 'de'
    subject TEXT NOT NULL,
    html_body TEXT NOT NULL,
    text_body TEXT,
    placeholders JSONB,                   -- Required placeholders
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    UNIQUE(template_key, language)
);

-- Vendor overrides
CREATE TABLE vendor_email_templates (
    id SERIAL PRIMARY KEY,
    vendor_id INTEGER REFERENCES vendors(id),
    template_key VARCHAR(100) NOT NULL,
    language VARCHAR(5) NOT NULL,
    subject TEXT NOT NULL,
    html_body TEXT NOT NULL,
    text_body TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    UNIQUE(vendor_id, template_key, language)
);

Rendering Flow

1. Email service receives request (e.g., send order confirmation)
2. Check for vendor override by (vendor_id, template_key, language)
3. If no override, use platform default by (template_key, language)
4. Render template with context variables
5. Send via email service

API Endpoints (Proposed)

Admin

• GET /admin/email-templates - List all platform templates
• GET /admin/email-templates/{key} - Get template by key
• PUT /admin/email-templates/{key} - Update platform template
• POST /admin/email-templates/{key}/preview - Preview template

Vendor

• GET /vendor/email-templates - List available templates with override status
• GET /vendor/email-templates/{key} - Get template (override or platform)
• PUT /vendor/email-templates/{key} - Create/update override
• DELETE /vendor/email-templates/{key} - Remove override (revert to platform)
• POST /vendor/email-templates/{key}/preview - Preview with vendor context

UI Considerations

• Admin: Template editor with WYSIWYG or code view
• Vendor: Simple override interface showing platform default as reference
• Placeholder validation on save
• Preview with sample data

Notes

• Email templates feature is NOT part of the current settings page
• Contact support messaging in settings directs vendors to admin
• Full implementation to follow CMS pages pattern