Layout & Design Templates

1. Executive Overview

What This Module Does

The Layout & Design — Page & Email Template System provides the complete visual management layer for the Hyphen Publishing Platform. It consists of two interconnected systems:

1. Page Template System — A visual drag-and-drop page builder that lets admins create, configure, and publish page layouts across 21 page categories (homepage, article, section, author, subscription, search, campaign, archive, shop, etc.). Published templates render on the Reader Portal as the public-facing magazine.

2. Email Template System — A template management system for all transactional, lifecycle, notification, and marketing emails. Admins can customize email content, branding, and behavior through a WYSIWYG editor with variable substitution, preview, and test-send capabilities.

Who Uses It

Business Problem Solved

• Eliminates the need for code changes to modify page layouts or email styling
• Provides consistent branding across all reader-facing pages and emails
• Enables non-technical staff to control magazine appearance and communication
• Supports 20+ page types with 80+ template variants and 176+ section components
• Centralizes email branding, variable management, and delivery tracking

2. Feature Scope

In Scope

Page Template System

Email Template System

Out of Scope

• A/B testing of page templates (not implemented)
• Drag-and-drop email editor (HTML-based editing only)
• Real-time collaborative editing (single editor at a time)
• Template marketplace or third-party template import

Related Modules / Dependencies

3. Roles Involved

Page Template System

Email Template System

RBAC Permissions Required

4. Architecture & Design Overview

System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         ADMIN CONSOLE                               │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Template      │  │ Email        │  │ Settings                 │  │
│  │ Canvas Editor │  │ Template     │  │ (Navigation, Appearance, │  │
│  │ + Gallery     │  │ Editor       │  │  Features, Paywall)      │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────────┘  │
│         │                  │                      │                  │
│  ┌──────▼──────────────────▼──────────────────────▼───────────────┐ │
│  │                    API Layer                                    │ │
│  │  /api/templates  /api/settings/email-templates  /api/settings  │ │
│  └──────┬──────────────────┬──────────────────────┬───────────────┘ │
│         │                  │                      │                  │
│  ┌──────▼──────┐   ┌──────▼──────┐   ┌──────────▼───────────────┐ │
│  │ PostgreSQL  │   │ PostgreSQL  │   │ Strapi CMS               │ │
│  │ (Prisma)    │   │ (Prisma)    │   │ (page-configuration,     │ │
│  │ PageTemplate│   │ EmailTemplate│  │  site-navigation,        │ │
│  │ PageCategory│   │ EmailLog    │   │  site-appearance,        │ │
│  │ TemplateVer │   │ EmailPrefs  │   │  page-template)          │ │
│  └──────┬──────┘   └─────────────┘   └──────────┬───────────────┘ │
│         │                                        │                  │
└─────────┼────────────────────────────────────────┼──────────────────┘
          │                                        │
          │          ┌─────────────────────┐       │
          └──────────▶   Strapi CMS        ◄──────┘
                     │   (Published Data)  │
                     └──────────┬──────────┘
                                │
                     ┌──────────▼──────────┐
                     │   READER PORTAL     │
                     │                     │
                     │  TemplateRenderer   │
                     │  DynamicTemplate    │
                     │  176 Section Comps  │
                     │  32 Template Files  │
                     │  ThemeProvider      │
                     └─────────────────────┘

Data Flow — Page Templates

1. Admin creates/edits template in Canvas Editor
2. API saves to PostgreSQL (PageTemplate + TemplateVersion) and writes versioned JSON file to /data/templates/
3. Admin publishes template → API syncs to Strapi CMS (page-configuration content type)
4. Reader Portal fetches page configuration from Strapi → resolves template → renders sections dynamically
5. Revalidation webhook triggers ISR cache refresh on Reader Portal

Data Flow — Email Templates

1. Admin creates/edits email template in Editor
2. API saves to PostgreSQL (EmailTemplate model)
3. System event triggers email (subscription welcome, OTP, campaign send, etc.)
4. Email Pipeline resolves template from DB → replaces variables → wraps with branding → sends via SMTP/provider → logs to EmailLog
5. Admin views delivery status in Email Logs page

Key Entities & Models

Page Template Models (PostgreSQL/Prisma)

Strapi Content Types

Email Models (PostgreSQL/Prisma)

Settings Precedence Model

The template system follows a 5-level precedence hierarchy:

Level 1: Global platform settings (DB)     — AUTHORITATIVE, NEVER overrideable
Level 2: Global site defaults (Strapi)     — AUTHORITATIVE with selective override
Level 3: Page template defaults            — OVERRIDE spacing/layout only
Level 4: Page-specific configuration       — Per-page overrides
Level 5: Content access rules              — OVERRIDE paywall per content

5. Prerequisites & Setup Requirements

Infrastructure Prerequisites

Environment Variables Required

Admin Console

Reader Portal

Module Dependencies (Must Be Set Up First)

Seed Data Initialization

Before the template system is usable, seed data must be initialized:

1. Page Categories — Seed 21 built-in categories:

   POST /api/page-categories/seed

2. Page Templates — Seed built-in templates:

   POST /api/templates/seed

3. Email Templates — Seed default email templates (subscription, campaign, notification, OTP, and operational):

   POST /api/settings/email-templates/seed

   Or click the "Seed Missing" button in Settings > Email Templates.

Strapi Content Types Required

The following content types must exist in Strapi:

• page-configuration (collection, draft & publish enabled)
• page-template (collection)
• page-version (collection)
• site-navigation (single type)
• site-appearance (single type)
• homepage (single type)
• static-page (collection)

6. Configuration Guide — Page Template System

6.1 Accessing the Template System

Navigate to Layout & Design in the admin console sidebar:

6.2 Understanding Page Categories

There are 21 built-in page categories:

6.3 Working with the Template Canvas Editor

Opening the Editor

1. Go to Layout & Design > Pages
2. Select a page type (e.g., Homepage)
3. Click on the assigned template or click Edit Template
4. The Canvas Editor opens with three panels:
   • Left Panel: Section Palette (drag sections from here)
   • Center Panel: Canvas Area (your page layout)
   • Right Panel: Properties Panel (configure selected section)

Adding Sections

1. In the Section Palette (left panel), browse section variants by category
2. Drag a section variant onto the Canvas Area
3. Drop it in the desired position (drop zones appear between existing sections)
4. The section appears on the canvas with default configuration

Configuring Section Properties

When you select a section on the canvas, the Properties Panel shows configuration options based on the section's behavior type:

Section Variant Categories

Reordering Sections

• Drag sections up or down on the canvas to reorder
• Section order property updates automatically

Removing Sections

• Select the section on the canvas
• Click the Delete/Remove button in the Canvas Toolbar or section context menu

Live Preview

• The LiveTemplatePreview component renders a real-time preview of the current template configuration
• Preview updates as you modify section properties

6.4 Template Versioning

Every template edit creates a version record:

Viewing Version History:

1. Open a template in the editor
2. Click Version History to see all versions
3. Each version shows: version number, change note, author, timestamp

Rolling Back:

1. In the version history, find the desired version
2. Click Rollback to this version
3. A new version is created with the rolled-back content (non-destructive)

6.5 Publishing Templates

Publishing syncs the template configuration to Strapi CMS, making it available to the Reader Portal.

1. Open the template in the editor
2. Review the configuration
3. Click Publish
4. The API:
   • Sets template status to active
   • Syncs template data to Strapi page-configuration content type
   • Triggers Reader Portal ISR revalidation
5. Changes appear on the Reader Portal within seconds

6.6 Managing Static Pages

1. Go to Layout & Design > Static Pages
2. Click Create to add a new page (or select existing)
3. Fill in:
   • Title — Page heading
   • Slug — URL path (e.g., about, privacy-policy, terms)
   • Category — Default: static
   • Template ID — Optionally bind to a template
   • Content — Rich text content
   • Active — Toggle visibility
4. Click Save

6.7 Managing Navigation

Navigate to Settings > Navigation or Navigation page.

Header Links

• Add, edit, reorder, or remove main navigation links
• Each link has: label, URL, and optional icon
• Changes sync to Strapi site-navigation single type

Footer Configuration

• Configure footer columns (each with title and list of links)
• Add social media links (X/Twitter, Facebook, Instagram, LinkedIn, etc.)
• Set copyright text and company information

6.8 Theme & Appearance

Navigate to Settings > Appearance.

Available customizations:

Changes sync to Strapi site-appearance and are consumed by the Reader Portal's ThemeProvider which applies them as CSS variables and Tailwind classes.

Live Preview: The appearance editor includes a live preview panel showing how changes will look on the Reader Portal.

7. Configuration Guide — Email Template System

7.1 Accessing Email Templates

Navigate to the Layout & Design sidebar group (previously under Settings):

7.2 Initial Setup — Seed Default Templates

Before email templates are usable, seed the defaults:

1. Go to Settings > Email Templates
2. Click the "Seed Missing" button in the header
3. This creates 20 default templates (only creates missing ones, never overwrites existing):

7.3 Creating / Editing Email Templates

1. Go to Settings > Email Templates
2. Click Create New or select an existing template
3. Fill in:

7.4 Using Template Variables

Variables are placeholders that get replaced with actual values at send time.

Syntax: {{variableName}} Matching: Case-insensitive (e.g., {{userName}} matches username)

System Variables (Auto-Injected)

These are always available in every template:

CRM Variables (Auto-Injected from CRM Settings)

Context-Specific Variables

7.5 Previewing Email Templates

1. In the template editor, click Preview
2. The preview renders the template with:
   • Branding wrapper (logo, header, footer from Email Preferences)
   • Sample variable values
   • Actual styling as it would appear in email clients

7.6 Sending Test Emails

1. In the template editor, click Send Test
2. Enter a recipient email address
3. The system sends the email with:
   • [TEST] prefix in subject line
   • Sample variable values
   • Full branding wrapper
4. Check the Email Logs page to verify delivery

7.7 Configuring Email Branding (Preferences)

Navigate to Settings > Email Templates > Preferences:

Important: Custom footer HTML is sanitized server-side to prevent XSS (strips scripts, iframes, event handlers, javascript: URLs).

7.8 SMTP / Provider Configuration

Navigate to Settings > Email Templates > Config:

1. Select the email provider: SMTP, SendGrid, or Mailchimp
2. Enter provider credentials
3. Click Test Connection to verify
4. Save configuration

Note: After changing provider configuration, the cached SMTP transporter may need a server restart to take effect (known anti-pattern, see Limitations section).

7.9 Viewing Email Logs

Navigate to Settings > Email Templates > Logs:

Additional features:

• Unsubscribe Analytics — Collapsible section showing: total unsubscribes, by reason, by category, 30-day timeline

8. How the Page Template System Works End to End

8.1 Template Lifecycle

Create Template → Edit Sections → Configure Properties → Preview → Publish → Render on Reader Portal
                                                                      │
                                                            Version Created
                                                            Sync to Strapi
                                                            Revalidate ISR

8.2 What Happens When You Publish

1. Template status set to active in PostgreSQL
2. Template data (sections, styles, banners) synced to Strapi page-configuration
3. Strapi stores as a published document (draft/publish workflow)
4. Reader Portal receives revalidation webhook
5. Next.js ISR regenerates affected pages
6. Readers see updated layout within seconds

8.3 Reader Portal Rendering Pipeline

1. Request arrives at Reader Portal (e.g., /fiction)
2. Next.js route resolves page type (e.g., "section")
3. Fetch page-configuration from Strapi for this page type
4. Extract templateId, sections[], banners[], styles
5. TemplateRenderer maps templateId → React component
6. DynamicTemplate iterates over sections[]:
   a. Resolve section variant → SectionRenderer → actual component
   b. Fetch section data based on contentSource (dynamic queries, manual IDs, mixed)
   c. Apply personalization boost if personalizationEnabled=true
   d. Render section component with data + properties
7. PageStyleOverrides applies page-level CSS overrides
8. BannerRenderer renders active banners (checks startsAt/endsAt)
9. ThemeProvider applies global appearance (colors, fonts, spacing)

8.4 Section Data Resolution

Each section can get content from different sources:

9. How the Email Template System Works End to End

9.1 Email Pipeline Flow

1. System event triggers email (e.g., new subscription)
2. Determine email class (mandatory-transactional, transactional-lifecycle, operational, marketing)
3. Resolve template:
   a. Look up EmailTemplate by key in DB
   b. If not found, use hardcoded fallback
4. Replace variables:
   a. Auto-inject system variables (site_name, support_email, etc.)
   b. Auto-inject CRM variables
   c. Replace caller-provided variables
   d. Case-insensitive matching
5. Wrap with branding:
   a. Load EmailPreferences from DB
   b. Apply header (logo, colors)
   c. Apply footer (company info, social links)
   d. Add unsubscribe link (if email class requires it)
   e. Add RFC 8058 List-Unsubscribe headers (if marketing/lifecycle)
6. Generate plain text fallback (strip HTML if textContent not provided)
7. Send via configured provider (SMTP/SendGrid/Mailchimp)
8. Log to EmailLog (template, recipient, status, provider, messageId)

9.2 Email Classes and Compliance

9.3 Unsubscribe Flow

1. Reader clicks unsubscribe link in email
2. Link contains HMAC token (generated from email + secret)
3. Reader Portal /unsubscribe page loads
4. If requireConfirmation enabled: a. Shows confirmation message b. Optional reason picker (admin-configured options) c. Grace period notice if configured
5. Reader confirms → API processes unsubscribe: a. Update Reader.newsletterOptIn b. Set AudienceContact.unsubscribedAt c. Create audit log entry d. If grace period > 0: store as pending, process via daily cron
6. Reader sees confirmation with category-specific message

10. Business Logic & Rules

Page Template Rules

Email Template Rules

Style Precedence

Global Appearance (Strapi) → Template defaultStyles → Page-specific styles

Override scope:

• spacing, containerWidth, fontFamily can be overridden at template and page level
• Colors, global fonts, and navigation are authoritative from global settings

11. Use Cases & Operational Scenarios

Page Template Use Cases

Email Template Use Cases

12. End-to-End User Flows

Flow 1: Create and Publish a New Page Template

Step 1: Admin navigates to Layout & Design > Pages
Step 2: Selects a page type (e.g., "Section")
Step 3: Clicks "Edit Template" or creates a new template
Step 4: Canvas Editor opens with three panels
Step 5: Admin drags sections from the palette onto the canvas:
        - HeroFullWidth (hero section)
        - FeaturedAboveGrid (featured articles)
        - Grid3Column (article grid)
        - NewsletterInline (newsletter signup)
Step 6: For each section, admin configures properties:
        - Content source: dynamic
        - Category filter: current section's category
        - Max items: 9
        - Sort order: newest first
Step 7: Admin clicks "Preview" to verify layout
Step 8: Admin clicks "Publish"
Step 9: System syncs to Strapi + triggers revalidation
Step 10: Reader Portal shows updated section page layout

Flow 2: Customize and Test an Email Template

Step 1: Admin navigates to Settings > Email Templates
Step 2: Locates "Subscription Welcome" template
Step 3: Opens the editor
Step 4: Modifies subject line: "Welcome to `{{site_name}}`, `{{userName}}`!"
Step 5: Edits HTML body with updated welcome message
Step 6: Clicks "Preview" — sees rendered email with branding
Step 7: Clicks "Send Test" → enters own email address
Step 8: Receives test email with [TEST] prefix
Step 9: Verifies styling, variables, branding in email client
Step 10: Clicks "Save" to persist changes
Step 11: Future welcome emails use the updated template

Flow 3: Configure Email Branding

Step 1: Admin navigates to Settings > Email Templates > Preferences
Step 2: Updates Header section:
        - Upload logo image URL
        - Set header background color
Step 3: Updates Footer section:
        - Company name, address
        - Social media links (Twitter, Facebook, etc.)
        - Copyright text
Step 4: Updates Unsubscribe section:
        - Grace period: 7 days
        - Require confirmation: Yes
        - Reason options: "Too many emails", "Not relevant", "Other"
Step 5: Clicks "Save"
Step 6: All future emails use updated branding

Flow 4: Manage Site Appearance and Navigation

Step 1: Admin navigates to Settings > Appearance
Step 2: Adjusts color theme (primary color, accent color)
Step 3: Selects font family for headings and body
Step 4: Adjusts spacing (container width, section padding)
Step 5: Previews changes in live preview panel
Step 6: Clicks "Save" → Strapi updated → Reader Portal revalidated

Step 7: Admin navigates to Settings > Navigation
Step 8: Adds "Programs" link to header navigation
Step 9: Reorders footer columns
Step 10: Adds Instagram social link
Step 11: Clicks "Save" → Changes appear on Reader Portal