[Design Discussion] Notification templates management support

[Thisara-Welmilla]

Related Feature Issue

#5337

Problem Summary

ThunderID ships a fixed set of email and SMS notification templates that can only be changed by editing server-side files and restarting the service. There is currently no runtime API or Console support for managing, customizing, or previewing them. This design makes templates manageable at runtime, localizable, brandable by composing the existing Design output at render time, and previewable through the Console.

High-Level Approach

1. Template scenario types (OTP, password recovery) follow the flow scope. A notification template is engaged through a flow node: the node defines which template scenario type is sent. Template scenario types therefore live in the same bounding scope as flows. A flow definition is a global object (deployment-scoped, with no app or OU); applications and organization units bind to a flow by reference. Because it is the global flow definition that references a scenario type, scenario types are global too.
2. Content belongs at the OU level, but is not supported this phase. While scenario types share the flow scope, the content of a scenario (subject / body per locale) naturally needs to be definable per organization unit (different OUs wording the same notification differently). That OU-level content capability is not supported in this phase: content is authored globally for now, and OU-level content is deferred to a later phase.

Template management

3. Store templates in the database as editable subject and body content, without branding, with a separate version for each locale. Also, include the default templates in the existing bootstrap bundle and import them during installation like other default resources.
4. Treat default and administrator-created templates as identical database resources.

Localization

6. Keep different content for the same template type per locale. A template scenario type can carry an independent content variant per locale (see Alternative 1), each with its own subject and body. Locale identifiers are validated as well-formed BCP-47 tags.

Branding resolution

8. Compose branding at render time Template content and branding treat as independent resources, so a single branding change applies to every template without editing content.

Preview

9. Provide a live, as-delivered preview in the flow UI in the Console, driven by the same resolve output the runtime uses (resolved content + composed branding + selected locale, with {{ctx(...)}} shown as-is), so an author sees the final message while editing only the pure content. It is surfaced on the top-level Notification Templates page (beside Design & Branding).

Proposed UIs

• Notification template section which list down all templates:

• A single notification template edit section:

Using templates in node execution

A template is engaged at runtime when a flow executes a node that sends a notification (an email/SMS node). The node references a template scenario type (Data model (1)); when execution reaches it, the runtime:

1. Resolves content for the recipient locale, falling back to the configured default locale when no variant matches, so a message is always produced: recipient-locale variant → default-locale variant.
2. Resolves and composes branding on top of the content, via Design at the application tier:application → default (skipped for SMS, which is plain text with no branding).
3. Substitutes the {{ctx(...)}} placeholders with the runtime data.
4. Hands the rendered message to the notification senders for delivery.

Flows need no structural change: the execution context already carries the appId (for branding) and the recipient locale; the email/SMS executor passes both into the resolution.

Proposed UIs

• Engage notification template to a flow:

• Preview branding applied notification in preview:

Architecture Overview

flowchart TB
    subgraph clients [Clients]
        Console["ThunderID Console<br/>template editor + preview"]
        ApiClient["API consumers<br/>SDKs / GitOps"]
    end

    subgraph nt [Notification Templates module]
        API["Notification Templates API"]
        MgmtSvc["Template Mgmt Service"]
        LocaleResolver["Locale Resolver<br/>recipient locale + default fallback"]
        BrandingResolver["Branding resolver"]
        Renderer["Renderer<br/>substitutes ctx placeholders"]
        Store[("Template store<br/>DB, mutable")]
    end

    subgraph install [Install-time]
        Bootstrap[("Bootstrap bundle<br/>cmd/server/bootstrap/*.yaml")]
        Importer["Import service<br/>Upsert true"]
    end

    subgraph reused [Reused services]
        Design["Design service<br/>branding configuration"]
    end

    subgraph consumers [Runtime consumers unchanged]
        Flow["Flow / authn / OTP"]
        Sender["Notification senders"]
    end
    Recipient["Recipient"]

    Console --> API
    ApiClient --> API
    API -->|manage / resolve| MgmtSvc
    Flow -->|resolve + render| MgmtSvc
    MgmtSvc --> Store
    Bootstrap -->|seed defaults at install| Importer --> Store
    MgmtSvc -->|pick locale| LocaleResolver
    MgmtSvc -->|apply branding| BrandingResolver --> Design
    MgmtSvc -->|substitute placeholders| Renderer
    MgmtSvc -.rendered notification.-> Flow
    Flow -->|deliver| Sender --> Recipient

Loading

Components

Component	Role	Status
internal/system/template	Template resolve + {{ctx(...)}} render pipeline	Extend: add mutable write path, locale key dimension
Template store (DB)	Templates + per-locale content, mutable	New DB-backed store, replacing today's read-only declarative file store
Bootstrap bundle + import service	Ships the default templates, seeded into the DB at install time (Upsert: true)	New resource_type: Template entries + import/export support
Locale resolver	Pick the recipient-locale variant, else the default locale	New
internal/design (/design/resolve)	Branding source, composed at render	Reuse (owned by Design)
Flow email/SMS executors + notification senders	Trigger and deliver notifications	Pass locale into Render(...); otherwise unchanged

Entity governance. All templates are uniform: there is no system/custom distinction. ThunderID preloads a default set of templates; administrators can create additional templates, and every template is managed the same way. Templates and their content are governed globally in this phase, and content carries per-locale variants. The default templates are shipped through the bootstrap bundle and seeded into the DB at install time, so after install they are ordinary mutable rows with nothing special
about them at runtime beyond being pre-created.

Template actions

Every template is managed the same way, whether it was preloaded or created by an administrator.

Action	Behaviour
Create	✓ create a new template; server assigns the id
Read / list	✓ all templates; content is returned locale-resolved
Update	✓ edit displayName; edit subject / body per locale
Delete	✓ delete a template and all its locale variants (guard for flow-referenced or preloaded templates; see open questions)

Data model and storage

There are two related models, both mutable DB rows seeded at install time by the bootstrap bundle (through the import service, Upsert: true) and edited afterward through the same API as any other template.

1. Template scenario type — keyed by (channel, typeId). One row per scenario per notification channel (for example email:otp, sms:otp, email:password-recovery). This is the entity a flow node references to choose which notification to send; it carries the displayName and holds no content of its own.
2. Template content — keyed by (Template scenario type, locale). One row per locale, holding the pure contentType, content. A scenario type has zero or more content rows, one per locale.

So templates get stored as raw with no branding markup.

Security Considerations

• AuthZ: every operation requires the system scope; unauthorized → AUTH-4010, forbidden business rules → AUTH-4030. Domain errors use the NTM-XXXX prefix and the shared Error/I18nMessage shape.
• Injection / templating: {{ctx(...)}} values are substituted only at send time; the preview never evaluates them. Rendered email is composed in a sandbox to contain XSS from authored HTML.
• Trusted authorship: template content is admin-authored (privileged), but the rendered output still reaches end users, so HTML is treated as untrusted at render.
• Input validation: channel, content type, required fields, referenced substitution variables, and BCP-47 locale tags are validated; malformed input is rejected without persisting.
• No empty delivery: an unresolvable type/locale (with no default-locale fallback) surfaces an explicit error at send time, and an empty or fabricated message is never delivered.

Impacted Areas

• internal/system/template: replace the read-only declarative file store with a DB-backed mutable store keyed (channel, typeId[, locale]); add create/update/delete/list and a locale dimension.
• Bootstrap + import service: add resource_type: Template import/export support and ship the default templates in the bootstrap bundle (cmd/server/bootstrap/), so defaults are DB-seeded at install like flows, groups, roles, and translations.
• internal/design (/design/resolve): reused to resolve branding at render; branding resolution is owned by Design, not this feature.
• Flow email/SMS executors: pass the recipient locale into Render(...); no structural flow change.
• New api/notification-templates.yaml; Console (top-level Notification Templates page + editor).

Alternatives Considered

The alternative below was considered but not selected.

Alternative 1: Use a translation catalog
Maintain one language-neutral template that references localized message keys from ThunderID’s existing translation resources.

• Pros: Avoids duplicating template structure; translators edit text instead of markup; structural changes apply across all languages.
• Cons: Limits language-specific structure and layout, including text order, length, and RTL support; large content blocks are awkward to manage as message keys.
  Decision: Not selected. Each locale retains a complete template, allowing language-specific structure and layout. This can be revisited if cross-language duplication becomes a significant concern.

Alternative 2: Support application-level content customization

Allow each application to override the content of notification templates.

• Pros: Enables application-specific messaging; flows already provide the required appId; aligns with application-level branding resolution.
• Cons: Introduces another content scope before the planned organization-unit tier and complicates governance through application, organization-unit, and global resolution.
  Decision: Not selected for this phase. Template content remains global. The intended future customization tier is the organization unit, while the application tier remains limited to branding.

Questions for Community Input

1. Template deletion. Deleting a template affects wherever it is used. Should deletion be blocked if the template is referenced by a flow?
2. Reset to shipped default. Should an edited default template be resettable to the version shipped in the bootstrap bundle (re-applying the bundle entry)?

[senthalan]

1. One thing to note in the component architecture: The runtime consumers should be using the providers not the service directly. So we have the create a TemplateProvider exposing only the needed functions
2. Can you define the Data model ?

[Thisara-Welmilla]

Updated Design Approach Decision

We have decide to proceed with the following decisions:

• All notification templates will be treated equally, with no distinction between default and custom templates. Therefore, all templates that are not in use can be deleted.
• A notification template cannot be deleted if it is currently being used in a flow.
• Since default templates are not treated as immutable resources after bootstrap, accidentally deleted default templates can be recreated easily. The default templates will be available as sample templates in the template creation wizard.

Furthermore, we decided to introduce the following user experience as well (But yet to decide which phase to deliver):

• Allow administrators to define reusable layouts for notification templates globally. Each notification template only needs to define the inner content displayed within the selected layout.

When the notification is resolved at send time, the content and layout will be rendered with the applicable theme from the app.

• Why we need this?

  • Avoid duplicating common content and styling across individual notification templates.
  • Allow administrators to update a global layout once and have the changes reflected across all templates using it.
  • Keep notification templates focused on their specific content while the layout handles the overall presentation.

• Approach

  • Notification layouts will be managed per notification channel by the Design feature through enhanced Design APIs and UI.
  • Notification template configuration (not per locale) will contain the branding references: Notification layout ID, Color theme (light/dark)
  • Users can select any available layout or choose no layout. In both cases, the notification content is configured will be treat in same manner and stored as HTML.
  • In the notification template configuration preview, users can: Define the notification content, Select a layout, Select an app to preview the notification with the applicable theme in real time.
  • Placeholder values will not be resolved in this preview. See Out of Scope.

Alternatives Considered

1. Managing layouts through the app

We considered managing notification layouts through the app, similar to themes and page layouts, as well as directly through notification templates.

We decided to manage layouts independently and associate them with notification templates. A common use case is for different notification types to have different layouts—for example, welcome and password reset emails may require different layouts even within the same app. Binding layouts to the app would limit this customization to the app level.

2. Restricting deletion of initial/default templates

We considered preventing deletion of default templates. However, the current architecture does not distinguish resources created during bootstrap from those created by users. Treating them differently would therefore will not align with the agreed architecture. Instead, all unused templates can be deleted, with default templates available as samples for easy recreation.

Out of Scope

1. Replacing placeholders with sample values in the template preview
   Although this would provide a better UX, it requires maintaining default values for each token type and locale. This should be handled as a broader capability shared across applicable features.

2. Notification previews in flows and apps
   The notification template management UI will provide the preview, including the selected layout and applicable theme. Separate previews within flows and apps are therefore out of scope for this phase.

Updated UIs will be shared soon.