# Notifications backend

Independent internal gRPC service with durable asynchronous email delivery.
The public contract belongs to [interface/proto/v1/interface.proto](interface/proto/v1/interface.proto).
Generated clients are build artifacts, not committed source.

## Architecture

The gRPC transport maps protobuf DTOs to domain requests. The service validates
and renders immutable template revisions, then saves a notification and its
pending-work state atomically in one document through the shared DB wrapper.
The outbox dispatcher publishes opaque IDs using shared messaging's durable
transport, adapted from Sendico. A durable NATS worker claims the notification
with an atomic conditional patch and saves the outcome before acknowledging.
`DriverConfig` selects the email driver: `sendgrid` or `resend`.

Email adapters only map rendered email models to provider wire payloads. SendGrid
uses adapted Sendico SDK construction; Resend uses its email HTTP API. Both support
subject, text and HTML, bounded timeouts and safe error classification.

## Run

Requires Go 1.27, protoc, an SXCHNGE MongoDB database and a NATS server with
JetStream enabled. Copy `config.example.yml` to an untracked `config.yml` here.
Set `SXCHNGE_MONGO_URI`, `SXCHNGE_NATS_URL`, a unique token of at least 32 bytes for
each configured caller, and the selected email provider's API key environment
variable. Configure a verified sender address, TLS certificate/key and template
catalog. Paths are relative to the process working directory.

From the root, run `make run-notifications`. The gRPC listener always uses TLS.
Use a private authenticated NATS endpoint; `tls://` URLs and credentials in the URL
are supported by the shared driver. Mongo and messaging both use shared
`DriverConfig` settings; email settings reject unknown keys.

The service provisions `SXCHNGE_NOTIFICATIONS` (file storage, 48-hour retention,
one replica), subject `sxchnge.notifications.email`, and durable consumer `email`.
This initial setup is for a single-replica deployment. Configure production
replication/provisioning policy in code before deploying to a clustered environment.
Multiple service workers can safely compete for jobs through atomic claims.

## Templates and parameters

See `templates.example.json`. Parameters use Go template map syntax such as
`{{.first_name}}`. Each revision declares the exact allowed parameter names and
locale-specific content. Missing/extra parameters, unknown revisions/locales and
invalid content are rejected before acceptance. Empty locale uses the default.
Values are data, not executable templates; HTML is escaped by `html/template`.
The catalog is loaded and compiled at startup. Never edit a published revision;
add a new version. Rendered payloads are persisted so retries do not depend on a
later catalog change. Recipient, body and subject are cleared on terminal state;
remaining status and request fingerprints expire through a seven-day TTL.

## Delivery semantics

- Send persists before returning; it does not wait for NATS or the email provider.
- Outbox scans every five seconds and republishes safely after a bus failure.
- Duplicate RPCs and duplicate broker deliveries do not create extra jobs/sends.
- Provider HTTP 2xx becomes ACCEPTED. No receipt/webhook or read tracking is claimed.
- Explicit rate limiting (429) retries with bounded exponential backoff and
  Retry-After, at most five provider attempts, bounded by message expiry.
- Transport errors, 408, 5xx and expired worker leases become UNKNOWN. These may
  have sent the email; operators must reconcile before requesting another send.
- Other provider failures are terminal. `provider_authentication_failed` signals
  credentials/permissions, `provider_rejected` a nonretryable rejection,
  `retry_exhausted` the attempt limit, and `expired` the message deadline.
- Resend receives the notification ID as its provider idempotency key. Its window
  is 24 hours. SendGrid has no equivalent guarantee; exactly-once external email
  delivery is not promised.
- Changing the configured driver fails queued jobs pinned to the old driver with
  `driver_changed`. Drain queued jobs before changing sender credentials/config.
- Callers authorize recipients and preferences. No direct customer-database access,
  bulk campaigns, provider failover, SMS, push or Telegram delivery is included.

Structured logs report notification IDs, driver, state and attempt count; message
content, template values, addresses and provider response bodies are excluded.
Monitor pending age, UNKNOWN/FAILED states and repeated outbox/worker warnings.

## Validate and distribute

`make test` and `make lint-backend` generate interfaces and validate all modules.
Notifications tests exercise real disposable MongoDB and NATS containers, concurrent
idempotency and claims, lease recovery, retries, transport authentication, rendering
and both provider payloads through local HTTP servers. No live emails are sent.
`make package-notifications-interface` prepares source and Go-client archives.
See [provenance](PROVENANCE.md) and [contract usage](interface/README.md).

Provider references: [SendGrid Mail Send](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send),
[Resend Send Email](https://resend.com/docs/api-reference/emails/send-email).