{"slug": "a-domain-driven-notification-microservice-patterns-from-production", "title": "A Domain-Driven Notification Microservice — Patterns From Production", "summary": "The article describes how notification systems in software projects often evolve from simple functions into complex systems requiring email, SMS, push notifications, and user preferences. The author advocates for applying domain-driven design (DDD) to separate notification concerns into three distinct layers: business code that emits domain events, a notification service that translates events into messages based on user preferences, and a dispatcher that handles delivery logic like quiet hours and channel filtering. This decoupled architecture prevents the business logic from being entangled with notification delivery details, making the system more maintainable and scalable.", "body_md": "Notifications start small. \"Send the user an email when their order ships.\" A function. A library. Done.\n\nA year later, you have email, SMS, push, in-app, Slack, and Microsoft Teams. You have user preferences per channel. You have quiet hours, batching, throttling, and a \"do not disturb\" mode. You have unsubscribe links and bounce handling. You have analytics on open rates and template-level metrics. You have multi-language templates and timezone-aware scheduling.\n\nWhat started as a function is now a system. If you keep it as a sprawling collection of `sendEmail`\n\nand `sendSlack`\n\nhelpers across your codebase, that system will eat your engineering team alive.\n\nThis is the shape of the notification microservice I built (and have rebuilt twice). The pattern isn't novel — it's domain-driven design applied to notifications — but the specifics matter.\n\n## The core insight\n\nA notification has three distinct concerns:\n\n-\n**What happened in the business**— \"order placed,\" \"user mentioned,\" \"invoice overdue.\" This is a domain event. -\n**What kind of message to send**— \"transactional email,\" \"high-urgency push,\" \"Slack mention.\" This is a delivery policy. -\n**How to actually send it**— \"render this template, then call the email provider's API.\" This is a channel adapter.\n\nMost codebases collapse all three into one function:\n\n```\nasync function sendOrderShippedEmail(orderId: string, userId: string) {\n  const user = await getUser(userId)\n  const order = await getOrder(orderId)\n  const html = renderTemplate('order-shipped', { user, order })\n  await sendgrid.send({ to: user.email, subject: 'Your order shipped', html })\n}\n```\n\nThis function knows about the domain event, the message type, and the channel. Three concerns. One function. Each one will change for different reasons, and changes will ripple across all the call sites.\n\nThe DDD-shaped version separates them.\n\n## Domain events\n\nThe business code emits an event. It doesn't know or care how the notification gets delivered.\n\n```\n// In your order service\nawait eventBus.publish({\n  type: 'order.shipped',\n  occurredAt: new Date().toISOString(),\n  data: {\n    orderId: order.id,\n    userId: order.userId,\n    trackingNumber: order.trackingNumber,\n  },\n})\n```\n\nThis is a fire-and-record operation. The order service is done. It moves on. The event lands in your event bus (BullMQ, Kafka, NATS, whatever).\n\nThe notification service consumes events. Its job is to translate \"order.shipped\" into \"a transactional email to the user with this template.\"\n\n## Notification preferences\n\nThe user's preferences live in a separate domain. They might be stored in the notification service's database or in a profile service — doesn't matter, as long as they're queryable:\n\n```\ntype UserNotificationPreferences = {\n  userId: string\n  channels: {\n    email: { enabled: boolean; address: string }\n    sms: { enabled: boolean; number?: string }\n    push: { enabled: boolean; deviceTokens: string[] }\n    slack: { enabled: boolean; userId?: string }\n  }\n  perEventType: Record<string, {\n    channels: ('email' | 'sms' | 'push' | 'slack')[]\n    enabled: boolean\n  }>\n  quietHours: { start: string; end: string; tz: string } | null\n}\n```\n\nWhen the notification service receives `order.shipped`\n\n, it looks up the user's preferences. The user has email enabled, SMS enabled, push enabled — but for this event type (`order.shipped`\n\n), they've only chosen email. So the service sends one email.\n\nThis decoupling is crucial. The business code emits one event. The notification service decides what to do with it based on user preferences. The user can change their preferences without anyone touching the business code.\n\n## The dispatcher\n\nThe middle layer is a dispatcher that:\n\n- Consumes an event.\n- Looks up the user's preferences.\n- Decides which channels to deliver on.\n- For each channel, builds a delivery job and queues it.\n\n```\ntype Channel = 'email' | 'sms' | 'push' | 'slack'\n\nclass NotificationDispatcher {\n  async handle(event: DomainEvent) {\n    const userId = (event.data as any).userId\n    if (!userId) return\n\n    const prefs = await this.prefsRepo.findByUserId(userId)\n    if (!prefs) return\n\n    const eventPrefs = prefs.perEventType[event.type]\n    if (!eventPrefs?.enabled) return\n\n    const now = new Date()\n    const channels = this.filterByQuietHours(eventPrefs.channels, prefs, now)\n\n    for (const channel of channels) {\n      await this.deliveryQueue.add('deliver', {\n        eventType: event.type,\n        userId,\n        channel,\n        eventData: event.data,\n        scheduledAt: now.toISOString(),\n      })\n    }\n  }\n\n  private filterByQuietHours(\n    requested: Channel[],\n    prefs: UserNotificationPreferences,\n    now: Date\n  ): Channel[] {\n    if (!prefs.quietHours) return requested\n    const isQuiet = isWithinQuietHours(now, prefs.quietHours)\n    if (!isQuiet) return requested\n    // During quiet hours, only allow non-disruptive channels (e.g., email/in-app)\n    return requested.filter(c => c === 'email' || c === 'in-app')\n  }\n}\n```\n\nThe dispatcher is pure routing logic. It doesn't render templates. It doesn't call any provider. It just figures out which channels to deliver on and queues delivery jobs.\n\n## Channel adapters\n\nEach channel is a separate worker that consumes jobs from the delivery queue and dispatches to its specific channel.\n\n```\nclass EmailDeliveryWorker {\n  async handle(job: DeliveryJob) {\n    if (job.channel !== 'email') return\n\n    const user = await this.userRepo.findById(job.userId)\n    const prefs = await this.prefsRepo.findByUserId(job.userId)\n    if (!user || !prefs?.channels.email.enabled) return\n\n    const template = await this.templateRepo.find(job.eventType, 'email')\n    const rendered = await this.renderer.render(template, {\n      user,\n      ...job.eventData,\n    })\n\n    await this.emailProvider.send({\n      to: prefs.channels.email.address,\n      from: rendered.from,\n      subject: rendered.subject,\n      html: rendered.html,\n      text: rendered.text,\n      headers: {\n        'X-Event-Type': job.eventType,\n        'X-User-Id': job.userId,\n        'List-Unsubscribe': `<${this.unsubscribeUrl(job.userId, job.eventType)}>`,\n      },\n    })\n\n    await this.deliveryLog.record({\n      userId: job.userId,\n      channel: 'email',\n      eventType: job.eventType,\n      sentAt: new Date().toISOString(),\n      provider: this.emailProvider.name,\n    })\n  }\n}\n```\n\nThe email worker knows about:\n\n- The user (to get their address).\n- The template store (to find the right template for this event type and channel).\n- The renderer (to fill in the template).\n- The email provider (to actually send).\n\nIt doesn't know about Slack, SMS, push, or any business logic. If I want to add a new channel, I add a new worker. The dispatcher already knows how to route to it (the channel is just a string in the job).\n\n## Templates as first-class entities\n\nA template store is its own small domain. Each template has:\n\n- An event type it's for (\n`order.shipped`\n\n). - A channel it's for (\n`email`\n\n,`sms`\n\n). - A language (\n`en`\n\n,`de`\n\n,`fr`\n\n). - A version (so changes are auditable).\n- The actual template content (HTML, plain text, Markdown).\n\n```\ntype Template = {\n  id: string\n  eventType: string\n  channel: Channel\n  language: string\n  version: number\n  subjectTemplate?: string       // for email\n  bodyTemplate: string\n  format: 'html' | 'markdown' | 'plain'\n  createdAt: string\n  active: boolean\n}\n```\n\nThe renderer takes a template and a context object and produces a rendered message. Use a templating library that has a sandboxed mode (Handlebars's strict mode, for example) — you do not want template authors writing arbitrary JS that gets executed during rendering.\n\n```\nclass Renderer {\n  async render(template: Template, context: Record<string, any>): Promise<Rendered> {\n    const compiled = Handlebars.compile(template.bodyTemplate, { strict: true })\n    const body = compiled(context)\n    const subject = template.subjectTemplate\n      ? Handlebars.compile(template.subjectTemplate, { strict: true })(context)\n      : undefined\n    return { body, subject, format: template.format }\n  }\n}\n```\n\nTemplates being stored in a database (not in code) means non-engineers can edit them. We had marketing folks editing email copy via an admin panel without ever touching a deploy.\n\n## The unsubscribe surface\n\nEvery notification should be unsubscribable. The dispatcher checks `enabled`\n\nflags before queuing, but the user needs a way to flip those flags. Two patterns:\n\n-\n**A preferences page in your app.** Standard. Each event type has a checkbox per channel. -\n**A one-click unsubscribe link in every notification.** Required by law in many jurisdictions for email marketing, and good UX everywhere.\n\nThe unsubscribe link encodes the user ID, the event type, and a signed token. Clicking it flips the preference:\n\n``` js\nfunction unsubscribeUrl(userId: string, eventType: string): string {\n  const token = sign({ userId, eventType, action: 'unsubscribe' })\n  return `https://app.example.com/api/notify/unsubscribe?token=${token}`\n}\n```\n\nThe endpoint verifies the token, updates the preference, and shows a \"you're unsubscribed\" page. The same endpoint can power the `List-Unsubscribe`\n\nheader for email clients that support one-click unsubscribe.\n\n## Observability\n\nEach delivery generates two records:\n\n-\n**Delivery log.**\"We attempted to send X to user Y on channel Z at time T using provider P.\" -\n**Provider callback.**\"The provider says message M was delivered (or bounced, or opened, or clicked).\"\n\nBoth feed into the same table, keyed by a message ID. The observability story collapses into \"show me everything that happened for user Y this week,\" which is what support teams ask for.\n\n## Throttling and batching\n\nTwo problems show up at scale:\n\n-\n**A user gets 50 notifications in 10 minutes** because something noisy happened. You need to batch them into a digest. -\n**A celebrity user's actions trigger 10,000 notifications to followers** in a burst. You need to throttle.\n\nThe dispatcher is where this logic lives. Before queuing a delivery, check a sliding-window counter (Redis-backed):\n\n```\nasync handle(event: DomainEvent) {\n  // ...existing routing logic...\n\n  for (const channel of channels) {\n    const window = `notify:${userId}:${channel}:${eventType}`\n    const count = await this.redis.incr(window)\n    if (count === 1) await this.redis.expire(window, 60)  // 1-minute window\n\n    if (count > MAX_PER_MINUTE) {\n      // Throttled. Queue for batching instead.\n      await this.batchQueue.add('batch', { userId, channel, eventType, eventData: event.data })\n    } else {\n      await this.deliveryQueue.add('deliver', { /* ... */ })\n    }\n  }\n}\n```\n\nThe batch worker runs periodically (every 5 minutes or whatever the digest schedule is), collects everything in the batch queue for a user, renders a \"digest\" template, and sends one combined notification.\n\n## What I'd warn the next team about\n\n**Don't put rendering in the dispatcher.** Keep the dispatcher routing-only. The dispatcher decides which channels to use; the workers decide how to render and send. Mixing them couples your routing logic to your template engine in ways that hurt later.\n\n**Use job retries with caution.** If the email provider returns a 503, retry. If it returns a 400 with \"invalid recipient,\" do not retry — that's a permanent failure. Different error codes have different retry semantics; encode this in the worker.\n\n**Track template performance.** Open rate per template per language is a real signal. Templates that score below 10% open rate are usually broken (bad subject line, bad timing, irrelevant content). Surface this in your admin UI.\n\n**Make the dead-letter queue visible.** Failed deliveries should go somewhere humans can see them. We had three months of bounces piling up before anyone noticed; turned out a customer had typo'd their email and was getting nothing. A weekly dashboard of \"delivery failures by user\" caught it.\n\n## The takeaway\n\nA notification microservice is one of the highest-leverage extractions you can do. The business code becomes simple (emit events). User preferences become a first-class concept. Templates become editable without deploys. New channels become new workers, not new branches in shared functions.\n\nThe pattern is more code than `sendgrid.send(...)`\n\n. It's also the difference between \"we have a notification feature\" and \"we have a notification platform.\" If you're shipping more than two notification types and you're tired of touching the same five functions every time product adds a new channel, this extraction pays for itself within a quarter.", "url": "https://wpnews.pro/news/a-domain-driven-notification-microservice-patterns-from-production", "canonical_source": "https://dev.to/hammadxcm/a-domain-driven-notification-microservice-patterns-from-production-a05", "published_at": "2026-05-22 21:06:57+00:00", "updated_at": "2026-05-22 21:32:43.492890+00:00", "lang": "en", "topics": ["developer-tools", "enterprise-software", "cloud-computing"], "entities": ["SendGrid", "Slack", "Microsoft Teams"], "alternates": {"html": "https://wpnews.pro/news/a-domain-driven-notification-microservice-patterns-from-production", "markdown": "https://wpnews.pro/news/a-domain-driven-notification-microservice-patterns-from-production.md", "text": "https://wpnews.pro/news/a-domain-driven-notification-microservice-patterns-from-production.txt", "jsonld": "https://wpnews.pro/news/a-domain-driven-notification-microservice-patterns-from-production.jsonld"}}