ScadaBridge/docs/plans/2026-06-19-sms-notifications-design.md

SMS Notifications (T9 pivot + T10) — Design

Date: 2026-06-19 Status: Approved (full scope) — proceed to implementation plan. Supersedes: the T9 "Teams delivery adapter" direction. T9/T10 were deferred to "next major version" in M6 (docs/plans/2026-06-17-m6-kpi-history-design.md). This design pulls them forward and pivots the second delivery channel from Microsoft Teams to SMS (Twilio).

---

Goal

Add NotificationType.Sms and a Twilio-REST SmsNotificationDeliveryAdapter behind the existing INotificationDeliveryAdapter seam, plus the T10 enum/UI/CLI plumbing, so notification lists can deliver to ZB team members by text message. Email delivery is unchanged.

Why the pivot (Teams → SMS)

The user's requirement is "notify ZB team members individually." Investigation of the current Microsoft Graph / Teams platform (2025–2026) established a hard architectural constraint:

• An outbound-only backend (our on-prem central cluster, which already does OAuth2 client-credentials to login.microsoftonline.com for SMTP) cannot send a full 1:1 chat-message body to a person via Graph. App-only chat sending is migration-only; real-time chat sending is delegated-user-only.
• A full-body per-person Teams DM requires a Bot Framework bot with a publicly-reachable inbound HTTPS endpoint that Azure Bot Service calls into the datacenter — a significant security/deployment change for an on-prem SCADA system.
• The only purely-outbound per-person Teams mechanism (sendActivityNotification) delivers a ~150-char headline + deep link, not a message body, and requires a published Teams app installed per recipient.

SMS sidesteps all of that: it is inherently per-person (recipient = phone number), carries a full message body, and is outbound-only (a single HTTPS POST to the provider). It is the natural "second delivery type" that makes the T10 Type selector meaningful.

Provider decision: Twilio, called directly over its REST API (no SDK), honoring the project's no-new-NuGet-package rule (central package management). Microsoft.Extensions.Http is already in central package management (used by NotificationService/ExternalSystemGateway); the NotificationOutbox project gains a <PackageReference> to it — no new package version is introduced.

Architecture

Mirror the existing Email/SMTP stack:

• A notification list's existing NotificationList.Type field decides the channel.
• Notify.To("list") / Notify.Send stay type-agnostic at the site.
• Central resolves the list's Type at ingest and stamps it on the Notification row; the outbox actor already dispatches via Dictionary<NotificationType, INotificationDeliveryAdapter> and parks on a missing adapter, so routing is automatic.

Tech stack

C#/.NET 10, Akka.NET, EF Core (MS SQL central), Blazor Server (Central UI), System.CommandLine (CLI), IHttpClientFactory, ASP.NET Data Protection (EncryptedStringConverter) for secret-at-rest. No new NuGet packages.

---

Decisions

D1 — Delivery adapter (Twilio REST)

• New SmsNotificationDeliveryAdapter : INotificationDeliveryAdapter (Type => NotificationType.Sms) in NotificationOutbox/Delivery, registered alongside the Email adapter in ServiceCollectionExtensions.
• Request: POST {ApiBaseUrl}/2010-04-01/Accounts/{AccountSid}/Messages.json, HTTP Basic auth (AccountSid:AuthToken), application/x-www-form-urlencoded body To / From (or MessagingServiceSid) / Body. Named HttpClient "Twilio" via IHttpClientFactory.
• Success = Twilio 2xx (message accepted/queued). Note: true delivery confirmation needs a status-callback webhook (inbound) — out of scope; "accepted by Twilio" is treated as Delivered, exactly as the Email adapter treats "accepted by the SMTP server."

D2 — Secret-at-rest (SmsConfiguration entity)

• New SmsConfiguration entity, provider-neutral name, mirroring SmtpConfiguration:
  • Id, AccountSid (plaintext — also appears in the URL path), AuthToken (encrypted via EncryptedStringConverter), FromNumber (E.164) and/or optional MessagingServiceSid, optional ApiBaseUrl (default https://api.twilio.com; lets tests point at a fake handler / supports regional), ConnectionTimeoutSeconds, MaxRetries, RetryDelay.
• EF: add AuthToken to ScadaBridgeDbContext.ApplySecretColumnEncryption. Idempotent migration adds the table.
• CredentialRedactor.Scrub(message, authToken) removes the AuthToken from any logged error.

D3 — Recipient model (per-list typing)

• A list is entirely Email or entirely SMS (single NotificationList.Type).
• NotificationRecipient gains a nullable PhoneNumber (E.164, e.g. nvarchar(32)); EmailAddress is relaxed to nullable (currently NOT NULL). Email-list recipients carry EmailAddress; SMS-list recipients carry PhoneNumber.
• Type-aware validation: SMS recipients require a valid E.164 PhoneNumber; Email recipients require a valid EmailAddress.
• Constructor/factory: keep NotificationRecipient(name, email); add an SMS construction path (factory NotificationRecipient.ForSms(name, phone) / ForEmail(name, email) or object-initializer support).
• Migration: additive nullable PhoneNumber column + one NOT-NULL→NULL relaxation on EmailAddress. Idempotent.

D4 — Message format

• SMS has no subject. Body = Subject + newline + Body (whichever present), plain text, truncated to a configurable cap (SmsOptions.MaxMessageLength, default 1600 = Twilio max) with an ellipsis when over.
• Doc caveat: Twilio segments at 160 GSM-7 chars and bills per segment.

D5 — Error classification

• Small local SmsErrorClassifier in NotificationOutbox/Delivery, mirroring the pattern of SmtpErrorClassifier (no cross-project reference to ExternalSystemGateway):
  • Transient: HTTP 5xx, 408, 429; HttpRequestException, TaskCanceledException/timeout (non-caller-cancel).
  • Permanent: other 4xx (incl. 401/403 bad creds, 400 invalid/unsubscribed number).

D6 — Per-recipient rollup (no SMS BCC → one POST per number)

• Send one Twilio request per recipient; classify each.
• All accepted → Success (ResolvedTargets = the numbers).
• Any transient → Transient (the whole notification retries at the fixed interval, then Parks after max-retries). Accepted caveat: numbers already accepted on a prior attempt get re-texted on retry — the same "re-send to all" characteristic the Email adapter already has with BCC. (v1 does NOT track per-recipient state; that is a documented future enhancement.)
• No transient, mix of accepted + permanent-bad → Success to the good numbers; permanently-bad numbers recorded in LastError. Do not park if anything got through.
• All permanent / no recipients / no SMS config / list-not-found → Permanent (Park).

D7 — Ingest type-stamping

• At NotificationOutboxActor ingest (currently hard-codes NotificationType.Email, ~line 1147), resolve the target list by ListName and stamp the Notification's Type from the list's Type (default Email if the list is not found — delivery parks on "list not found" regardless). Keeps Notify.To type-agnostic.

D8 — T10 UI/CLI plumbing

• NotificationType.Sms added to the enum.
• Create/UpdateNotificationListCommand gain NotificationType Type (additive, default Email); handlers persist it.
• CLI: notification list create/update --type email|sms, with --emails (email lists) / --phones (sms lists).
• Central UI NotificationListForm: an adapter-gated Type selector — it offers only NotificationType values that have a registered INotificationDeliveryAdapter (Email + SMS today; auto-extends if more are added). The recipient input switches email↔phone by the selected type with appropriate validation.
• Type is chosen at create and is fixed on edit (prevents email/phone recipient mismatch within a list).
• NotificationLists list page gains a Type column.
• New SMS-config management mirroring SMTP: ListSmsConfigsCommand / UpdateSmsConfigCommand (+ HandleListSmsConfigs / HandleUpdateSmsConfig, role-gated like SMTP, audited via a credential-free public shape), CLI notification sms list|update, Admin-only Central UI page /notifications/sms.

D9 — Transport

• NotificationRecipientDto gains a nullable PhoneNumber (backward-compatible: omitted = null).
• New SmsConfigDto (secret rides the existing SecretsBlock), mirroring SmtpConfigDto, carried in BundleContentDto / EntityAggregate and round-tripped by EntitySerializer.

---

Blast radius (file-level)

Commons

• Types/Enums/NotificationType.cs — add Sms.
• Entities/Notifications/NotificationRecipient.cs — add PhoneNumber; SMS construction path.
• Entities/Notifications/SmsConfiguration.cs — new.
• Messages/Management/NotificationCommands.cs — add Type to Create/Update list commands; add ListSmsConfigsCommand / UpdateSmsConfigCommand.
• Interfaces/Repositories/INotificationRepository.cs — add SMS-config read/write methods (mirror SMTP).

Configuration Database

• Configurations/NotificationConfiguration.cs — EmailAddress nullable, PhoneNumber mapping; SmsConfiguration mapping.
• ScadaBridgeDbContext.cs — ApplySecretColumnEncryption adds SmsConfiguration.AuthToken; DbSet<SmsConfiguration>.
• Repository impl — SMS-config methods.
• New idempotent EF migration (PhoneNumber + EmailAddress-nullable + SmsConfiguration table).

NotificationOutbox

• Delivery/SmsNotificationDeliveryAdapter.cs — new.
• Delivery/SmsErrorClassifier.cs — new.
• ServiceCollectionExtensions.cs — register SMS adapter + named "Twilio" HttpClient.
• NotificationOutboxActor.cs — ingest type-stamping (D7).
• *.csproj — add Microsoft.Extensions.Http PackageReference (already centrally managed).
• SmsOptions (ScadaBridge:Sms) — timeout / max-length (retry reuses outbox settings where possible).

Management Service

• ManagementActor.cs — HandleListSmsConfigs / HandleUpdateSmsConfig (+ role gating + audit public shape); list-command handlers persist Type.

CLI

• Commands/NotificationCommands.cs — --type + --phones on list create/update; notification sms list|update group.
• CLI README.md.

Central UI

• Components/Pages/Notifications/NotificationListForm.razor — Type selector (adapter-gated) + per-type recipient input.
• Components/Pages/Notifications/NotificationLists.razor — Type column.
• Components/Pages/Notifications/SmsConfiguration.razor — new (/notifications/sms, mirror SMTP page).
• Nav entry for the SMS config page.

Transport

• Serialization/EntityDtos.cs — PhoneNumber on recipient DTO; SmsConfigDto.
• Serialization/EntitySerializer.cs — map SMS config + recipient phone both directions.
• BundleContentDto / EntityAggregate — include SMS configs.

Tests (break / add)

• Update NotificationOutbox.Tests/ServiceRegistrationTests.cs — Assert.Single(adapters) → assert Email and SMS registered.
• New SmsNotificationDeliveryAdapter unit tests (fake HttpMessageHandler: 201 / 5xx / 429 / timeout / 400 / 401 / rollup / redaction).
• Ingest type-stamping test.
• CLI tests (--type, --phones, sms group).
• bUnit: Type selector (adapter-gated), per-type recipient editor, Type column.
• EF/migration config tests.
• Playwright: SMS-list create flow (INT).

Docs / deploy

• docs/requirements/Component-NotificationService.md, Component-NotificationOutbox.md.
• CLAUDE.md decision notes (NotificationType = Email+Sms; T9/T10 delivered as SMS, not deferred; flip the M6 deferral note).
• README.md component table / CLI README as needed.
• Docker: no new secret (SMS config lives in DB like SMTP); minimal ScadaBridge:Sms options.

---

Out of scope / deferred (logged, not built)

• Per-recipient delivery-state tracking to avoid duplicate texts on retry (v1 uses unit-retry, matching Email-BCC; see D6).
• Twilio status-callback (inbound) webhook for true delivery confirmation.
• Microsoft Teams delivery (dropped).
• Mixed email+phone single list (per-list typing only).
• Editable list Type after creation.

Execution

• Dedicated worktree feat/sms-notifications off main (c72d7b79); pathspec commits (-m before --, never git add -A); targeted builds/tests per task; full-solution build + docker rebuild + Playwright + live smoke at INT; then finishing-a-development-branch (merge-to-local-main per established pattern — push only on explicit confirmation).
• Plan + .tasks.json co-located in docs/plans/. Subagent-driven execution (classification-driven review chains).