Notification Service Architecture

Production - 5 controllers, 7 channels, state machine delivery

The Notification Service is the multi-channel notification delivery backbone of the MATIH platform. Running on port 8085, it handles sending notifications through email, SMS, push, Slack, Microsoft Teams, in-app, and webhook channels. It includes template management with variable substitution, user preference tracking, delivery analytics with open/click tracking, and unsubscribe management compliant with RFC 8058.

Service Overview

Property	Value
Service Name	`notification-service`
Port	8085
Technology	Spring Boot 3.2, Java 21
Database	PostgreSQL (JPA/Hibernate)
Event Bus	Kafka (notification events)
Email	SMTP (configurable: SendGrid, SES, etc.)
State Machine	Spring State Machine for delivery lifecycle

Controllers

Controller	Base Path	Purpose
`NotificationController`	`/api/v1/notifications`	Send, retry, cancel notifications
`TemplateController`	`/api/v1/templates`	Template CRUD, preview rendering
`PreferenceController`	`/api/v1/preferences`	User notification preferences
`TrackingController`	`/api/v1/notifications/track`	Open/click tracking, analytics
`UnsubscribeController`	`/api/v1/notifications/unsubscribe`	Unsubscribe management

Notification Delivery Pipeline

Send Request -> Validate -> Resolve Template -> Check Preferences
       |            |             |                    |
       v            v             v                    v
   Enqueue -> Route to Channel -> Deliver -> Track Events
                    |                |            |
              +-----+-----+         v            v
              |     |     |    Record Status   Analytics
            Email  Slack  Push
            SMS   Teams  Webhook
                  In-App

Notification State Machine

Notifications follow a state machine lifecycle:

PENDING -> QUEUED -> SENDING -> DELIVERED
              |          |          |
              v          v          v
           FAILED    FAILED     BOUNCED
              |          |
              v          v
          RETRYING   RETRYING -> DELIVERED | FAILED

Status	Description
`PENDING`	Created, not yet queued
`QUEUED`	In the delivery queue
`SENDING`	Being processed by a channel
`DELIVERED`	Successfully delivered
`FAILED`	Delivery failed (retryable or permanent)
`RETRYING`	Scheduled for retry
`CANCELLED`	Cancelled before delivery
`BOUNCED`	Email bounced back

Channels

Channel	Implementation	Description
`EMAIL`	`EmailChannel`	SMTP-based email delivery
`SMS`	`SmsChannel`	SMS via configured provider
`PUSH`	`PushChannel`	Mobile push notifications
`SLACK`	`SlackChannel`	Slack webhook integration
`TEAMS`	`TeamsChannel`	Microsoft Teams webhook
`IN_APP`	`InAppChannel`	In-application notifications
`WEBHOOK`	`WebhookChannel`	Custom HTTP webhook delivery

All channels implement the NotificationChannel interface:

public interface NotificationChannel {
    void send(Notification notification, RenderedTemplate template);
    boolean supports(Notification.Channel channel);
}

Next Steps

Notification Service Sending Notifications