# cds-snc/notification-utils architecture

> Architecture diagram of the GitHub repository cds-snc/notification-utils, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cds-snc/notification-utils
- Repository: https://github.com/cds-snc/notification-utils

## Overview

notifications-utils is a shared Python library for Notification, not a standalone message-sending service. Its central workflow is to validate and normalize recipient data, personalize and format message templates, and provide rendered outputs to consuming applications; email samples exercise that rendering capability. Separate utilities support billing rates, logging, concurrency, status checks, and external clients. The graph reflects documented and indexed references; unsampled modules are included where they represent substantial capabilities, but their internal call relationships are not inferred.

Main entry points: [`notifications_utils/template.py`](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/template.py) (Message templates), [`notifications_utils/recipients.py`](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/recipients.py) (CSV recipients), [`notifications_utils/formatters.py`](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/formatters.py) (Text formatters), [`scripts/email_samples/generate.py`](https://github.com/cds-snc/notification-utils/blob/main/scripts/email_samples/generate.py) (Sample email renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Message content"]
  node_template["Message templates<br/>[template.py]"]
  node_field["Personalisation fields<br/>[field.py]"]
  node_formatters["Text formatters<br/>[formatters.py]"]
  node_sanitise["Text sanitisation<br/>[sanitise_text.py]"]
  node_html["HTML validation<br/>[validate_html.py]"]
  node_assets["Email assets<br/>[email_assets.py]"]
  node_strftime["Date format codes<br/>[strftime_codes.py]"]
  node_template_change["Template comparison<br/>[template_change.py]"]
end

subgraph group_recipients["Recipient data"]
  node_recipients["CSV recipients<br/>[recipients.py]"]
  node_columns["Rows and columns<br/>[columns.py]"]
  node_rates["International billing rates"]
end

subgraph group_infra["Shared services"]
  node_redis["Redis client<br/>[redis_client.py]"]
  node_annual["Annual limits<br/>[annual_limit.py]"]
  node_bounce["Bounce rate<br/>[bounce_rate.py]"]
  node_logging["Logging utilities<br/>[logging.py]"]
  node_parallel["Parallel execution<br/>[parallel.py]"]
  node_antivirus["Antivirus client"]
  node_statsd["StatsD client<br/>[statsd_client.py]"]
  node_zendesk["Zendesk client<br/>[zendesk_client.py]"]
end

subgraph group_samples["Email samples"]
  node_samples["Sample definitions<br/>[samples.py]"]
  node_sample_generator["Sample email renderer<br/>[generate.py]"]
end

node_consumers(("Notification applications"))

node_consumers -->|"provide recipient data"| node_recipients
node_consumers -->|"use shared templates"| node_template
node_field -->|"normalizes columns"| node_columns
node_field -->|"uses formatters"| node_formatters
node_formatters -->|"uses sanitisation"| node_sanitise
node_recipients -->|"normalizes row data"| node_columns
node_recipients -->|"uses formatters"| node_formatters
node_recipients -->|"uses billing rates"| node_rates
node_recipients -->|"checks template data"| node_template
node_template -->|"personalizes content"| node_field
node_template -->|"uses column helpers"| node_columns
node_template -->|"formats content"| node_formatters
node_template -->|"sanitizes content"| node_sanitise
node_template -->|"validates HTML"| node_html
node_template -->|"uses email assets"| node_assets
node_template -->|"uses date codes"| node_strftime
node_template -->|"compares templates"| node_template_change
node_annual -->|"stores limit data"| node_redis
node_bounce -->|"stores bounce data"| node_redis
node_sample_generator -->|"renders definitions"| node_samples
node_sample_generator -->|"renders templates"| node_template
node_sample_generator -->|"embeds local assets"| node_assets

click node_template "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/template.py"
click node_field "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/field.py"
click node_formatters "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/formatters.py"
click node_sanitise "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/sanitise_text.py"
click node_html "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/validate_html.py"
click node_assets "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/email_assets.py"
click node_strftime "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/strftime_codes.py"
click node_template_change "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/template_change.py"
click node_recipients "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/recipients.py"
click node_columns "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/columns.py"
click node_rates "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/international_billing_rates.py"
click node_redis "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/redis/redis_client.py"
click node_annual "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/redis/annual_limit.py"
click node_bounce "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/redis/bounce_rate.py"
click node_logging "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/logging.py"
click node_parallel "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/parallel.py"
click node_antivirus "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/antivirus/antivirus_client.py"
click node_statsd "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/statsd/statsd_client.py"
click node_zendesk "https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/zendesk/zendesk_client.py"
click node_samples "https://github.com/cds-snc/notification-utils/blob/main/scripts/email_samples/samples.py"
click node_sample_generator "https://github.com/cds-snc/notification-utils/blob/main/scripts/email_samples/generate.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_template,node_field,node_formatters,node_sanitise,node_html,node_assets,node_strftime,node_template_change toneBlue
class node_recipients,node_columns,node_rates toneAmber
class node_redis,node_annual,node_bounce,node_logging,node_parallel,node_antivirus,node_statsd,node_zendesk toneMint
class node_samples,node_sample_generator toneRose
class node_consumers toneIndigo
```

## Components

### Message content

- [Message templates](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/template.py): `notifications_utils/template.py`
- [Personalisation fields](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/field.py): `notifications_utils/field.py`
- [Text formatters](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/formatters.py): `notifications_utils/formatters.py`
- [Text sanitisation](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/sanitise_text.py): `notifications_utils/sanitise_text.py`
- [HTML validation](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/validate_html.py): `notifications_utils/validate_html.py`
- [Email assets](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/email_assets.py): `notifications_utils/email_assets.py`
- [Date format codes](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/strftime_codes.py): `notifications_utils/strftime_codes.py`
- [Template comparison](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/template_change.py): `notifications_utils/template_change.py`

### Recipient data

- [CSV recipients](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/recipients.py): `notifications_utils/recipients.py`
- [Rows and columns](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/columns.py): `notifications_utils/columns.py`
- [International billing rates](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/international_billing_rates.py): `notifications_utils/international_billing_rates.py`

### Shared services

- [Redis client](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/redis/redis_client.py): `notifications_utils/clients/redis/redis_client.py`
- [Annual limits](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/redis/annual_limit.py): `notifications_utils/clients/redis/annual_limit.py`
- [Bounce rate](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/redis/bounce_rate.py): `notifications_utils/clients/redis/bounce_rate.py`
- [Logging utilities](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/logging.py): `notifications_utils/logging.py`
- [Parallel execution](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/parallel.py): `notifications_utils/parallel.py`
- [Antivirus client](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/antivirus/antivirus_client.py): `notifications_utils/clients/antivirus/antivirus_client.py`
- [StatsD client](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/statsd/statsd_client.py): `notifications_utils/clients/statsd/statsd_client.py`
- [Zendesk client](https://github.com/cds-snc/notification-utils/blob/main/notifications_utils/clients/zendesk/zendesk_client.py): `notifications_utils/clients/zendesk/zendesk_client.py`

### Email samples

- [Sample definitions](https://github.com/cds-snc/notification-utils/blob/main/scripts/email_samples/samples.py): `scripts/email_samples/samples.py`
- [Sample email renderer](https://github.com/cds-snc/notification-utils/blob/main/scripts/email_samples/generate.py): `scripts/email_samples/generate.py`

### Other components

- **Notification applications**

## Connections

- Notification applications → CSV recipients: provide recipient data (evidence: `README.md`)
- Notification applications → Message templates: use shared templates (evidence: `README.md`)
- Personalisation fields → Rows and columns: normalizes columns (evidence: `notifications_utils/field.py`)
- Personalisation fields → Text formatters: uses formatters (evidence: `notifications_utils/field.py`)
- Text formatters → Text sanitisation: uses sanitisation (evidence: `notifications_utils/formatters.py`)
- CSV recipients → Rows and columns: normalizes row data (evidence: `notifications_utils/recipients.py`)
- CSV recipients → Text formatters: uses formatters (evidence: `notifications_utils/recipients.py`)
- CSV recipients → International billing rates: uses billing rates (evidence: `notifications_utils/recipients.py`)
- CSV recipients → Message templates: checks template data (evidence: `notifications_utils/recipients.py`)
- Message templates → Personalisation fields: personalizes content (evidence: `notifications_utils/template.py`)
- Message templates → Rows and columns: uses column helpers (evidence: `notifications_utils/template.py`)
- Message templates → Text formatters: formats content (evidence: `notifications_utils/template.py`)
- Message templates → Text sanitisation: sanitizes content (evidence: `notifications_utils/template.py`)
- Message templates → HTML validation: validates HTML (evidence: `notifications_utils/template.py`)
- Message templates → Email assets: uses email assets (evidence: `notifications_utils/template.py`)
- Message templates → Date format codes: uses date codes (evidence: `notifications_utils/template.py`)
- Message templates → Template comparison: compares templates (evidence: `notifications_utils/template.py`)
- Annual limits → Redis client: stores limit data (evidence: `notifications_utils/clients/redis/annual_limit.py`)
- Bounce rate → Redis client: stores bounce data (evidence: `notifications_utils/clients/redis/bounce_rate.py`)
- Sample email renderer → Sample definitions: renders definitions (evidence: `scripts/email_samples/generate.py`)
- Sample email renderer → Message templates: renders templates (evidence: `scripts/email_samples/generate.py`)
- Sample email renderer → Email assets: embeds local assets (evidence: `scripts/email_samples/generate.py`)
