Notification Service — Service Overview
Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: DOMAIN_MODEL · API_CONTRACTS · EVENT_SCHEMAS
1. Purpose
notification-service delivers transactional email and SMS notifications to users and administrators in response to platform lifecycle events. It:
- Consumes events from multiple NATS subjects:
auth.events,billing.events,operator.health,system.alerts. - Resolves notification preferences per account/user to respect opt-outs by category.
- Renders templates using Handlebars + Mjml (email HTML) or plain text (fallback and SMS).
- Delivers via SendGrid (email) and Ghasi platform (SMS, via sms-orchestrator — low-priority queue).
- Maintains a full notification audit log for every delivery attempt.
This service has no public REST API — it is purely event-driven. A single internal endpoint allows admin-dashboard to manage notification templates; health/metrics endpoints are also exposed internally.
2. Bounded Context
User & Admin Notifications — Generic / infrastructure concern. Does not own user preferences (auth-service owns the user record); it owns per-account notification preferences.
3. Responsibilities
| Area | What notification-service owns |
|---|---|
| Event consumption | NATS consumer on auth.events, billing.events, operator.health, system.alerts |
| Preference resolution | notification_preferences table; per-account opt-out by category |
| Template management | notification_templates table (id, type, channel, subject, body_html, body_text, variables_schema) |
| Template rendering | Handlebars variable substitution; Mjml → HTML compilation; plain-text fallback |
| Email delivery | SendGrid HTTP API |
| SMS delivery | Ghasi platform (POST to sms-orchestrator) with low-priority metadata |
| Notification audit log | notification_log — every attempt, channel, status, error |
| Template admin | Internal endpoint (no Kong route): admin-dashboard can CRUD templates |
4. Non-Responsibilities
| Area | Owner |
|---|---|
| User identity / email address management | auth-service |
| SMS routing and operator selection | sms-orchestrator + routing-engine |
| Billing event production | dlr-processor / billing-service |
| Customer-facing notification preferences UI | customer-portal (calls auth-service + this service's internal endpoint) |
| Alert escalation to PagerDuty | SRE alerting stack (Grafana OnCall) |
| Marketing / bulk emails | External marketing tool |
5. Dependencies
| Dependency | Kind | Purpose |
|---|---|---|
| NATS JetStream | Event bus (consumer) | auth.events, billing.events, operator.health, system.alerts |
PostgreSQL (schema notif) | Data store | notification_log, notification_preferences, notification_templates |
| SendGrid API | External HTTP | Email delivery |
| sms-orchestrator | Internal HTTP | SMS delivery (low-priority channel) |
| auth-service | Internal HTTP | Resolve email address from accountId/userId |
| Mjml library | In-process | Email HTML compilation |
6. High-Level Flow
7. Key Design Decisions
| Decision | Rationale | Trade-off |
|---|---|---|
| Pure event-driven; no public REST API | Notifications are side-effects of platform events; no synchronous caller | Admin must trigger test notifications via admin-dashboard |
| Templates stored in DB, not filesystem | Admin-dashboard can update templates without a deployment | Template errors can affect production; mitigated by variables_schema validation and staging preview |
| Mjml for email HTML | Industry-standard responsive email DSL; avoids manual table-based HTML | Adds Mjml compile step; acceptable overhead |
| SMS via sms-orchestrator, not direct SMPP | Reuses existing rate-limiting, operator routing, and audit trail | Extra HTTP hop; acceptable for low-priority notifications |
| Per-account opt-out (not global) | Platform sends transactional notifications that some roles must not suppress (e.g. security alerts) | Some categories (SYSTEM_SECURITY) ignore opt-out |
| Handlebars variables_schema in DB | Validate template at admin-save time; catch missing variables before production delivery | Schema must be kept in sync with event-to-notification mappers |
8. Status
Greenfield service. Gated on: NATS stream provisioning for all consumed subjects, SendGrid API key provisioned via Vault, sms-orchestrator deployment live (SMS channel). See SERVICE_READINESS.