Email Template System - Deep Dive Documentation¶

Generated: 2026-02-25 Scope: Full-stack — Backend EmailTemplate module + shared email services + entity + frontend visual builder + legacy v1 Files Analyzed: 44 Lines of Code: ~10,600+ Workflow Mode: Exhaustive Deep-Dive Known Issues Found: 60 (6 Critical, 10 High, 23 Medium, 21 Low) — Expert Panel reviewed: 5 recalibrated, 9 added, 1 removed Security Analysis: Red Team Attack Scenarios — 5 attack chains, 2 CRITICAL (SQL injection → DB compromise, Stored XSS → privilege escalation) Architecture Decisions: ADRs — 3 ADRs: unify email infra (4h), connect DB templates to sending (6h), delete v1 (5min) Pre-mortem Analysis: Failure Scenarios — 7 incidents: 2 catastrophic (SQL injection breach, XSS takeover), 1 certain (permission lockout), 1 insidious (silent email failure) Root Cause Analysis: 5 Whys — 5 chains → 3 systemic causes: zero test coverage, super_admin-only dev, no integration tracking

Overview¶

The Email Template System is a full-stack feature consisting of a backend CRUD module for managing email templates in the database, a visual drag-and-drop email builder on the frontend (v2), a legacy monolithic builder (v1), and an email sending infrastructure with three providers (Nodemailer, Resend, Brevo) using a factory pattern.

Critical Architectural Finding: The database-stored templates managed by the visual builder are completely disconnected from the actual email sending pipeline. All emails are sent using hardcoded TypeScript template functions in src/template/. The EmailTemplate CRUD module is a design/management tool with zero integration into email dispatch.

Purpose: Enable admins to design, manage, and store email templates via a visual builder; provide email sending infrastructure for transactional emails (verification, OTP, password reset, invitations).

Key Responsibilities: - Template CRUD with soft-delete, bulk operations, restore, trash management - Visual email builder with 11 element types, drag-and-drop, undo/redo, HTML import/export - 5 template presets (Purchase, Verification, Order, Invitation, Password Reset) - Email dispatch via 3 providers (Nodemailer, Resend, Brevo) with factory pattern - Transactional email templates for auth flows (hardcoded, separate from DB templates)

Integration Points: Auth system (email verification, OTP, password reset), Invite system, RBAC permissions, Config/environment variables, Database (PostgreSQL + TypeORM)

Architecture Overview¶

                    ┌─────────────────────────────────────────────────┐
                    │              EMAIL TEMPLATE SYSTEM              │
                    │                                                 │
                    │  ┌──────────────┐    ┌────────────────────┐     │
                    │  │  DESIGN PATH │    │   SENDING PATH     │     │
                    │  │  (Connected) │    │   (Disconnected)   │     │
                    │  │              │    │                    │     │
                    │  │  Frontend    │    │  Event Handlers    │     │
                    │  │  Builder UI  │    │  ├ registerEmail   │     │
                    │  │      │       │    │  ├ sendLoginOtp    │     │
                    │  │      ▼       │    │  ├ sendForgotPass  │     │
                    │  │  API CRUD    │    │  ├ inviteUserCreate│     │
                    │  │  10 endpoints│    │  └ inviteOnlyLogin │     │
                    │  │      │       │    │        │           │     │
                    │  │      ▼       │    │        ▼           │     │
                    │  │ email_       │    │  src/template/     │     │
                    │  │ templates    │    │  (5 hardcoded      │     │
                    │  │ (DB table)   │    │   TS functions)    │     │
                    │  │              │    │        │           │     │
                    │  │  ╳ DEAD END  │    │        ▼           │     │
                    │  │  Never read  │    │  EmailFactory OR   │     │
                    │  │  for sending │    │  helper/email.ts   │     │
                    │  └──────────────┘    │        │           │     │
                    │                      │        ▼           │     │
                    │                      │  SMTP / Resend /   │     │
                    │                      │  Brevo API         │     │
                    │                      └────────────────────┘     │
                    └─────────────────────────────────────────────────┘

Dual Email Sending Infrastructure¶

The system has two parallel, incompatible email sending architectures:

Both must be configured independently via different environment variables.

Complete File Inventory¶

Backend — EmailTemplate Module (4 files, ~460 LOC)¶

Backend — Email Services (9 files, ~285 LOC)¶

Backend — Legacy Email Helpers (3 files, ~97 LOC)¶

Backend — Hardcoded Templates (5 files, ~65 LOC)¶

Backend — Entity (1 file, ~35 LOC)¶

Frontend — API Layer (1 file, 238 LOC)¶

Frontend — v2 Components (20 files, ~6,372 LOC)¶

Frontend — Utilities (6 files, ~2,178 LOC)¶

Frontend — Legacy v1 (2 files, ~1,783 LOC)¶

Frontend — Page Routes (4 files)¶

Database Schema¶

email_templates Table¶

CREATE TABLE email_templates (
    id          SERIAL PRIMARY KEY,
    title       VARCHAR(255) DEFAULT NULL,
    type        VARCHAR(255) NOT NULL UNIQUE,
    subject     VARCHAR(255) DEFAULT NULL,
    elements    JSONB NOT NULL,
    html        TEXT NOT NULL,
    "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "deletedAt" TIMESTAMP DEFAULT NULL
);

Relationships: None. Completely standalone entity — no foreign keys to or from any other table.

Migrations: None. Project uses synchronize: true in development. No migration files exist for any entity.

Seed Data: None. No email template records or permissions are seeded.

Indexes: Only PK (id) and UNIQUE (type). No index on deletedAt despite frequent soft-delete queries.

API Endpoints¶

Mounted at /api/v1/email-templates with auth() + contextMiddleware on all routes.

Note: All permission checks are done inside service methods via checkPermissionAndThrow(), not via route-level hasPermission middleware. This is inconsistent with how other modules handle permissions.

Frontend API Hooks (10 hooks + 1 phantom)¶

Email Template Data Model (Frontend Builder)¶

GlobalStyles Object¶

{
  bodyBackground: "#f4f4f4",       // Body/page background
  containerBackground: "#ffffff",   // Email container background
  containerWidth: "600",           // Container max-width (px)
  containerPadding: "20",          // Outer padding (px)
  contentPadding: "30",            // Inner content padding (px)
  borderRadius: "8",              // Container border-radius (px)
  fontFamily: "Arial, sans-serif", // Base font
  linkColor: "#007bff",           // Default link color
  baseFontSize: "14",             // Base font size (px)
  lineHeight: "1.6",              // Base line-height
}

Element Types (11 types)¶

All elements also have: id (string), type (string), isHidden (boolean, optional).

Template Presets (5)¶

Email Sending Infrastructure¶

Provider Comparison¶

Nodemailer Transport Instances (Triple!)¶

IEmailSendPayload Declarations (Triple!)¶

Environment Variables¶

Frontend Component Architecture¶

Component Hierarchy¶

email-templates/page.js
  └── EmailTemplatesPage
       ├── DataTable (list view with tabs: Active/Draft/Trash)
       ├── ConfirmationModal (delete/restore dialogs)
       └── EmailPreview (preview modal with dangerouslySetInnerHTML)

email-templates/create/page.js
  └── EmailTemplateForm (builder)
       ├── Toolbar (undo/redo, device preview, import/export)
       ├── ElementToolbox (11 draggable element types)
       ├── SortableElement[] (@dnd-kit sortable list)
       │    └── Action buttons (move up/down, duplicate, hide, delete)
       ├── ElementEditor
       │    ├── ElementEditorContent (type-specific content fields)
       │    └── ElementEditorStyle (type-specific style fields)
       ├── GlobalStylesPanel
       ├── InteractiveEmailPreview (click-to-select preview)
       ├── SaveTemplateModal (title, type, subject)
       ├── HtmlExportModal (copy/download HTML)
       ├── HtmlImportModal (paste/upload HTML)
       ├── TemplateSelectorModal (5 presets)
       ├── MobileBottomNav (responsive)
       ├── MobileToolboxDrawer (responsive)
       └── MobilePropertiesDrawer (responsive)

email-templates/[id]/page.js
  └── PermissionWrapper (email-template.create — WRONG, should be .update)
       └── EmailTemplateEditPage
            └── EmailTemplateForm (same builder, prefilled with existing data)

State Management¶

The EmailTemplateForm component manages ALL state locally via useState and useReducer:

No Redux, no Context — fully self-contained component state.

User Flow: Creating an Email Template¶

1. Navigate to /dashboard/email-templates (requires email-template.view permission in sidebar)
2. Click "Add New" button (requires email-template.create permission check)
3. Redirected to /dashboard/email-templates/create (NO server-side permission check)
4. Choose a preset template from selector OR start blank
5. Add elements from toolbox (drag-and-drop via @dnd-kit)
6. Click elements to select → edit content and styles in side panel
7. Preview in desktop/tablet/mobile modes
8. Optionally import HTML from external source
9. Click "Save" → fill title, type (purpose), subject in modal
10. Template saved to email_templates table via POST /api/v1/email-templates
11. HTML is generated client-side via generateFullHtml() and sent with the save request
12. Template sits in database — never used for actual email sending

User Flow: Editing an Email Template¶

1. From list page, click edit icon on a template
2. Navigated to /dashboard/email-templates/[id]
3. useEmailTemplateById fetches template data
4. elements array loaded into builder state
5. Edit as needed, save via PATCH /api/v1/email-templates/:id

HTML Generation Pipeline¶

elements[] + globalStyles → generateFullHtml() → Full HTML5 email document

HTML Import Pipeline¶

HTML string → DOMParser → parseHtmlToElements() → { elements[], globalStyles }

Generator/Parser Asymmetry¶

Dependency Graph¶

Backend Dependencies¶

email_template.routes.ts
  ├── email_template.controller.ts
  │    └── email_template.service.ts
  │         ├── EmailTemplate (entity)
  │         ├── checkPermissionAndThrow (helper)
  │         ├── getDbRepository (shared)
  │         ├── parsePaginationQuery (helper)
  │         └── requestContext (shared)
  └── email_template.validation.ts
       └── validateRequest (middleware)

EmailFactory.ts (NOT connected to EmailTemplate module)
  ├── NodeMailerService.ts
  ├── ResendService.ts
  └── BrevoService.ts

helper/email.ts (NOT connected to EmailTemplate module)
  ├── helper/transporterMail.ts
  └── helper/email/resend.ts

Frontend Dependencies¶

email-templates/page.js
  └── email-templates-page.jsx
       ├── api/email-templates/index.js (10 hooks)
       ├── components/ui/* (DataTable, Dialog, etc.)
       └── hooks/useCheckPermission.js

email-templates/create/page.js & [id]/page.js
  └── email-template-form.jsx
       ├── utils/constants.js (ELEMENT_TYPES, DEFAULT_*)
       ├── utils/utils.js (generateId, historyReducer)
       ├── utils/html-generator.js (generateFullHtml)
       ├── utils/html-parser.js (parseHtmlToElements)
       ├── utils/template-presets.js (TEMPLATE_PRESETS)
       ├── sortable-element.jsx (@dnd-kit/sortable)
       ├── element-editor.jsx
       │    ├── element-editor-content.jsx
       │    └── element-editor-style.jsx
       ├── element-toolbox.jsx
       ├── toolbar.jsx
       ├── global-styles-panel.jsx
       ├── interactive-email-preview.jsx
       ├── save-template-modal.jsx
       ├── html-export-modal.jsx
       ├── html-import-modal.jsx
       ├── template-selector-modal.jsx
       ├── form-fields.jsx
       ├── mobile-bottom-nav.jsx
       ├── mobile-toolbox-drawer.jsx
       └── mobile-properties-drawer.jsx

Entry Points (Not imported by others in scope)¶

• email-templates/page.js — list page
• email-templates/create/page.js — create page
• email-templates/[id]/page.js — edit page
• email-templates-v1/create/page.js — legacy v1 create
• email_template.routes.ts — backend route entry

Leaf Nodes (Don't import others in scope)¶

• email.type.ts — type definitions only
• IEmailService.ts — interface only
• utils/constants.js — constants only
• utils/utils.js — utilities only
• form-fields.jsx — reusable form fields

Circular Dependencies¶

• utils/index.js line 19: export * from "../utils" resolves to itself (circular barrel re-export). Should be export * from "./utils".

Testing Analysis¶

Test Coverage: 0% — No test files exist anywhere in the project.

Testing Gaps: - No unit tests for service CRUD operations - No unit tests for HTML generator (element → HTML) - No unit tests for HTML parser (HTML → elements) — this is the most complex file at 845 LOC - No integration tests for API endpoints - No component tests for the builder UI - No E2E tests for template creation workflow - No validation testing for edge cases (empty elements, malformed HTML, XSS payloads)

Suggested Tests: 1. html-generator.test.js — Test each element type generates correct HTML 2. html-parser.test.js — Test round-trip fidelity for each element type 3. email_template.service.test.ts — Test CRUD, soft-delete, restore, bulk operations 4. email_template.routes.test.ts — Test auth, permissions, validation 5. EmailFactory.test.ts — Test provider selection, singleton behavior 6. email-template-form.test.jsx — Test builder interactions, undo/redo, DnD

Security Analysis — Red Team Attack Chains¶

Full analysis: docs/extra-docs/email-template-attack-scenarios.md

Attacker profile: Authenticated user with zero permissions (freshly registered).

Critical path: Chain 1 → Chain 2 creates a realistic "new signup → super_admin in <5 minutes" scenario by combining orderBy SQL injection, dangerouslySetInnerHTML stored XSS, and the known PATCH /users/profile self-role-change vulnerability.

P0 fixes (block both CRITICAL chains in ~45 min): 1. Whitelist orderBy values (15 min) 2. Add DOMPurify to template preview (30 min)

Known Issues¶

Expert Panel Review (2026-02-25): Winston (Architect), Amelia (Dev), Quinn (QA) peer-reviewed all issues. 5 severity recalibrations, 9 new issues added, 1 removed (L9 was a valid re-export, not circular). Original 52 → 60.

Critical (6)¶

High (10)¶

Medium (23)¶

Low (21)¶

Severity Summary¶

Related Code & Reuse Opportunities¶

Similar Patterns Elsewhere¶

Reusable Utilities Available (Not Used by Email Templates)¶

Modification Guidance¶

Detailed ADRs with implementation plans, code samples, and phasing: docs/extra-docs/email-template-adrs.md

ADR-1: Unify Email Infrastructure (~4 hrs)¶

Consolidate all sending onto lib/email/EmailFactory.ts. Extend IEmailSendPayload with to: string | string[], optional attachments, optional from. Migrate 3 legacy handlers (sendLoginOtp, sendForgotPass, inviteOnlyLogin) to getEmailService().sendEmail(). Delete 6 legacy/dead files. Single EMAIL_SERVICE env var replaces both EMAIL_SERVICE and MAIL_TYPE.

ADR-2: Connect DB Templates to Sending (~6 hrs)¶

New lib/email/templateResolver.ts: query email_templates by type with 5-min TTL cache, interpolate {{variables}} via Mustache-like replacement, fall back to hardcoded TypeScript template if no DB record found. Update 5 event handlers (3-line change each). Seed 5 default templates matching current hardcoded HTML. Seed email-template.* permissions.

ADR-3: Delete Legacy v1 (~5 min)¶

Delete email-templates-v1/ directory (2 components + 1 route page). v2 is a complete superset. Git history preserves code.

To Add a New Element Type¶

1. Add type constant to utils/constants.js → ELEMENT_TYPES
2. Add default properties to DEFAULT_ELEMENTS
3. Add content editor section in element-editor-content.jsx
4. Add style editor section in element-editor-style.jsx
5. Add HTML generation case in html-generator.js
6. Add HTML parser case in html-parser.js
7. Add icon and label in element-toolbox.jsx

Implementation Phasing¶

Phase 1 — P0 Security (~45 min):  Whitelist orderBy + DOMPurify preview
Phase 2 — ADR-3 (~5 min):         Delete v1 builder
Phase 3 — ADR-1 (~4 hrs):         Unify email infrastructure
Phase 4 — ADR-2 (~6 hrs):         Connect DB templates to sending
Phase 5 — Follow-up (backlog):    Insert Variable UI, elements validation,
                                   sandboxed iframe, image upload integration

Testing Checklist for Changes¶

• Verify all 10 API endpoints return correct responses
• Test permission checks: each endpoint denies unauthorized users
• Test getAllTemplates — confirm if permission bypass is intentional
• Test create with duplicate type — verify proper error handling
• Test bulk restore — verify type conflict handling
• Test HTML generation for each element type
• Test HTML parser round-trip for each element type
• Test undo/redo with multiple operations
• Test drag-and-drop reordering
• Test HTML import with various email HTML formats
• Test preset template loading
• Test save/update with all field combinations
• Test trash/restore/permanent-delete flows
• Test mobile responsive builder UI
• Test orderBy parameter with SQL injection payloads
• Test bulk-permanent-delete resolves to valid endpoint

Contributor Checklist¶

Risks & Gotchas: - The orderBy SQL injection (C1) is the highest-priority security fix - getAllTemplates permission bypass (C2) exposes all template data - The dual email infrastructure means changes to email sending must be made in TWO places - Frontend and backend have different permission expectations (e.g., email-template.trash only exists in frontend) - The elements JSONB has no schema — any shape is accepted and stored - HTML preview uses dangerouslySetInnerHTML — XSS risk if templates contain malicious content

Pre-change Verification Steps: 1. Check which email sending path your change affects (factory vs helper) 2. Verify permission strings match between frontend and backend 3. Test with non-super_admin user (permissions won't exist unless manually created) 4. Check both .env vars: MAIL_TYPE AND EMAIL_SERVICE

Suggested Tests Before PR: 1. Run the app, attempt template CRUD as non-super_admin — verify behavior 2. Test GET /email-templates/all without permission — should it be allowed? 3. Test orderBy=1;DROP TABLE-- on GET /email-templates 4. Test bulk operations with conflicting types 5. Create template, export HTML, import HTML — verify round-trip fidelity

Generated by document-project workflow (deep-dive mode) Base Documentation: docs/index.md Scan Date: 2026-02-25 Analysis Mode: Exhaustive