Guides
  1. architecture-decisions

0017. Notification Service Template Storage

Status: Accepted Date: 2026-01-23 Context: Where and how notification templates (email, SMS, push) are stored, versioned, and scaled.

Context

The Notification Service requires template storage for email, SMS, and push notifications. Templates need to:

  • Be versioned and managed (draft → active)
  • Support HTML and text formats
  • Scale to high throughput (thousands of notifications per minute)
  • Integrate with existing platform infrastructure (AWS, LocalStack)

Template Storage Options:

  • PostgreSQL - Relational database, simple queries
  • DynamoDB - NoSQL, scalable, serverless
  • S3 - Object storage, versioning support
  • Hybrid - Metadata in DB, assets in S3

Note: Template engine selection is covered in ADR-0018.

Decision

Template Storage: AWS DynamoDB + S3 (Hybrid)

Primary Storage: DynamoDB

  • Store template metadata and content in DynamoDB table notification-templates
  • Partition Key: template_id (String)
  • Sort Key: version (Number) for version history
  • Attributes: channel, activation_status, metadata, content (subject, html_body, text_body, placeholders)

Large Assets: S3

  • Store large HTML bodies, images, attachments in S3
  • DynamoDB item contains S3 reference (optional)
  • S3 Object Versioning for asset versioning

Why DynamoDB:

  • Scalability - Fully managed, horizontally scalable NoSQL
  • Security - Fine-grained AWS IAM permissions
  • Concurrency - Conditional writes prevent overwrite conflicts
  • Integration - Native AWS integration (Lambda, AppConfig, API Gateway)
  • Reliability - Point-in-Time Recovery (PITR)
  • Existing Infrastructure - Platform already uses DynamoDB (via LocalStack)

Why S3 for Assets:

  • Large Content - Better for large HTML bodies, images
  • Versioning - S3 Object Versioning for asset history
  • Cost - Lower cost for large files

Rationale

Why DynamoDB (Not PostgreSQL):

  1. Scalability - Better suited for high-throughput read patterns (template lookups)
  2. Serverless - Fully managed, no connection pooling concerns
  3. Existing Infrastructure - Platform already uses DynamoDB
  4. Versioning - Natural fit for versioned templates (PK/SK pattern)
  5. Multi-Region - Easier multi-region deployment

Why Not PostgreSQL:

  1. Read-Heavy - Templates are read-heavy (lookup by templateId), DynamoDB optimized for this
  2. Simple Queries - No complex joins needed, DynamoDB sufficient
  3. Scaling - DynamoDB scales automatically, PostgreSQL requires more management

Consequences

Positive:

  • Scalability - DynamoDB scales automatically for high throughput
  • Integration - Native AWS integration (DynamoDB, S3)
  • Versioning - Natural versioning support (DynamoDB + S3)
  • Cost - Efficient storage (DynamoDB for metadata, S3 for large assets)
  • Existing Infrastructure - Platform already uses DynamoDB

Negative / Tradeoffs:

  • DynamoDB Learning Curve - Team must understand DynamoDB patterns
  • Query Limitations - DynamoDB has limited query capabilities (GSI required for complex queries)
  • S3 Integration - Requires S3 client setup for large assets
  • LocalStack - Must ensure LocalStack DynamoDB support for local development

Mitigations:

  • Documentation - Clear DynamoDB schema and access patterns
  • GSI - Use Global Secondary Indexes for query patterns (e.g., by channel)
  • LocalStack - LocalStack fully supports DynamoDB
  • Examples - Provide examples of template storage and retrieval

Implementation

DynamoDB Schema:

Table: notification-templates

  • Partition Key: template_id (String)
  • Sort Key: version (Number)
  • Attributes:
    • channel (String) - EMAIL, SMS, PUSH
    • activation_status (String) - ACTIVE, DRAFT, ARCHIVED
    • metadata (Map) - tags, owner, last_modified
    • content (Map) - subject, html_body, text_body, placeholders
    • s3_reference (String) - Optional S3 key for large assets

GSI: channel-index

  • Partition Key: channel
  • Sort Key: template_id
  • For listing templates by channel

Qute Template Rendering:

// Retrieve template from DynamoDB
Template template = templateRepository.getTemplate("welcome-email-v1");

// Render with Qute
String rendered = Qute.fmt(template.getHtmlBody())
    .data("firstName", "John")
    .data("activationLink", "https://example.com/activate?token=abc123")
    .render();

Template Storage Pattern:

  1. Small Templates - Store directly in DynamoDB content.html_body
  2. Large Templates - Store in S3, reference in DynamoDB s3_reference
  3. Versioning - New version = new DynamoDB item (same template_id, different version)
  4. Activation - activation_status field indicates active version

Related Decisions

  • ADR-0012: Clean Architecture Package Structure (package organization)
  • ADR-0015: Fire-and-Forget / Asynchronous Messaging Pattern (async processing)
  • ADR-0018: Notification Service Template Engine Selection (template rendering engine)

Future Considerations

Template Versioning:

  • Current: Immutable templates (new version = new item)
  • Future: May add explicit versioning strategy if needed

Template Management UI:

  • Future: Admin UI for template management
  • Current: API-only or seed scripts

Multi-Language Support:

  • Future: Per-template locales or locale variable
  • Current: Single language

Updated 10 days ago