Notifications And Communications

Summary

Notifications and communications cover the platform's outbound communication capabilities: email, Microsoft Graph, Teams destinations, Postmark delivery, and scheduled morning-brief communication. The module is a capability surface used by jobs and workflows rather than a standalone inbox product.

Module At A Glance

Reader Question

How does the platform send operational communication while keeping provider behavior, recipients, payloads, and tests explicit?

Surface Or Workflow

Operators mostly experience notifications as delivered artifacts: morning briefs, Teams destinations, email results, and provider-backed communication. Engineers enter through notification services, integration clients, jobs, morning-brief libraries, lakehouse pipelines, and compatibility tests.

Lifecycle

A workflow or scheduled job builds a communication payload. Capability services adapt it to email, Graph, Teams, or Postmark. Provider integrations execute the send or destination sync. Tests and runbooks validate recipients, evidence, payload compatibility, and baseline samples.

Architecture Rationale

Communication looks like a side effect, but operational messages need policy, stable payloads, provider isolation, retry state, and audit evidence. Domain workflows should create intent; notification capabilities should own delivery semantics.

Child Threads

Implementation Boundaries

Notification services live under services/notifications; notification jobs under jobs/notifications; provider adapters under integrations/ext_postmark and integrations/ext_microsoft; morning brief libraries under libs/morning_brief; payload/email jobs under jobs/lakehouse; lakehouse transforms under pipelines/lakehouse/transform/gold/morning_brief*.

Tradeoffs

Communication looks like a side effect, but operational communication needs the same discipline as sync: stable payloads, explicit recipients, provider boundaries, and evidence when something fails or changes.

Visual

The current visual is a graph neighborhood. The intended visual is a communication flow from workflow payload to notification service, provider adapter, recipient/destination, delivery result, and support evidence.

Communication As Platform Capability

Notifications should be treated as a platform capability because many domains need to communicate without owning provider details. A morning brief, campaign message, precon RFI, operational alert, diagnostic summary, or Teams update may all look like "send a message" from the outside. Internally they differ by payload shape, recipient policy, evidence, provider, retry behavior, and audit requirements. The shared capability gives domains a consistent way to request delivery while preserving those differences.

This also keeps communication from becoming a hidden side effect. A job should not casually call an email provider after doing unrelated work. It should produce or request a communication payload with enough context to validate, render, send, and diagnose. Notification services can then decide how to adapt that payload to Postmark, Microsoft Graph, Teams, or another channel. Provider adapters perform the external call and return structured outcomes.

The module is intentionally not an inbox product. It is the outbound communication layer for operational workflows. That distinction keeps the surface focused on payload correctness, delivery state, provider diagnostics, and recipient policy rather than attempting to model all human communication.

Morning Brief As Reference Workflow

The morning brief is the clearest example because it crosses lakehouse facts, prompted validation, payload construction, and email delivery. A scheduled workflow builds an operational summary from data products. Validation checks whether the generated or assembled content is safe enough to send. Payload jobs turn the summary into a communication artifact. Delivery jobs send it through the notification capability.

Each step has a different owner. Lakehouse publication owns source facts. Morning brief libraries own payload and validation contracts. Notification services own delivery behavior. Provider integrations own the external send. Tests protect compatibility across those boundaries. That separation is what lets a support person distinguish a missing source fact from an invalid brief, a rendering issue, a recipient problem, or a provider failure.

The same pattern should apply to other communications. A precon RFI draft may have a different human approval path, but it still needs payload evidence, recipient context, provider isolation, and delivery result. A marketing message may include suppression and attribution, but it still needs delivery diagnostics. A production alert may have different urgency, but it still needs stable recipient and channel policy.

Delivery State And Diagnostics

Communication failures should become inspectable state. The platform should be able to show whether a payload was never created, failed validation, lacked a recipient, failed provider dispatch, received a provider rejection, or was sent successfully. These states lead to different repairs. Rebuilding a payload will not fix a provider authentication problem. Retrying provider delivery will not fix missing source evidence.

Delivery state also supports audit. Operational messages often explain why an operator took action or why a customer received communication. The system should preserve what was sent, through which channel, to which destination, under which policy, and with what provider outcome. That does not mean every message becomes a full case record. It means the delivery layer should return enough structured evidence for the owning workflow to record what matters.

Provider diagnostics belong behind the same boundary. Postmark and Microsoft Graph have different concepts, but the platform should expose internal delivery results that support retry and repair. A domain should not need to parse provider-specific responses to decide whether a communication is done.

Recipient And Policy Context

Recipients are part of the contract. A message without explicit recipient context is hard to audit and hard to repair. The platform should know whether a destination is an email address, mailbox, Teams channel, internal operator, or provider-specific identity. It should also know whether the workflow is allowed to use that destination. Marketing suppression, operational alert routing, and morning brief distribution are different policies, but each should be explicit.

This policy layer becomes more important as the platform grows. More workflows will want to send messages. Without a shared communication boundary, each domain will invent its own recipient logic, provider client, retry behavior, and diagnostics. The notifications module prevents that spread while still allowing each domain to own the meaning of the message.

How Domains Should Use The Capability

A domain should enter the notification layer with intent and context, not with provider code. Marketing should know the campaign, audience, suppression, and message context. Precon should know the artifact or RFI context. Operations should know the alert or diagnostic summary. Morning brief should know the payload and distribution policy. The notification capability can then render, route, dispatch, and record delivery state through the appropriate provider boundary.

This separation makes tests more meaningful. Domain tests can assert that the right communication intent is produced. Notification tests can assert payload compatibility, recipient policy, provider adaptation, and delivery-state behavior. Provider tests can focus on boundary translation and error handling. Each layer protects a different risk.

The result is a communication platform that can grow without forcing every workflow to become an email integration. New channels may still require new provider adapters and policy decisions, but the domain contract stays stable: produce explainable communication intent and let the shared capability handle delivery semantics.

The same contract is useful for support. When someone asks whether a message went out, the answer should not depend on reading provider logs by hand. The platform should be able to show the payload, recipient policy, rendered message, dispatch attempt, provider outcome, retry state, and owning workflow. That evidence is what makes communication an operational capability instead of a best-effort side effect. It also gives future channels a clear standard.

Source Evidence

  • docs/domains/notifications.md
  • services/notifications
  • jobs/notifications
  • integrations/ext_postmark
  • integrations/ext_microsoft
  • libs/morning_brief
  • jobs/lakehouse/morning_brief_payload/run.py
  • jobs/lakehouse/morning_brief_email/run.py
  • pipelines/lakehouse/transform/gold/morning_brief_email
  • tests/pipelines/test_morning_brief_packet_contracts.py