Notification Service — Sync Contract

Status: populated Owner: Platform Engineering Last updated: 2026-04-18

1. Per-Aggregate Policy

Aggregate	Policy	Rationale
NotificationLog	server_authoritative	Immutable after insert; read via admin internal endpoint
NotificationPreference	server_authoritative	Updated by admin-dashboard; no client-side sync
NotificationTemplate	server_authoritative	Admin-managed; versioned append-only history

2. Offline Behavior

No offline behavior. This service is event-driven and requires live NATS connectivity to function. Admin template management requires live HTTP connection to the internal endpoint.

3. Event Consumption Ordering

Notifications for the same accountId may arrive out of order (NATS does not guarantee per-account ordering across subjects). This is acceptable — each notification is an independent delivery action with no ordering dependency.

4. Replay Tolerance

• NATS redelivery: duplicate source_event_id detected via notification_log check → SUPPRESSED. Ensures at-most-one delivery.
• Template updates mid-delivery: rendering uses the template version active at dispatch time (loaded fresh from DB each dispatch).
• If delivery fails after all retries, the event is ACKed and the notification is marked FAILED. There is intentionally no automatic re-queue — a failed notification log entry alerts ops for manual follow-up.