Unity Notifications Service - Project Overview

Solution Structure

The solution (Unity.Notifications.sln) contains 14 projects:

Application Projects

Project	Type	Framework	Description
Unity.Notifications.Web	Web API	.NET 8.0	Main API for notification management — email uploads, SMS webhooks, bounce handling
EmailMessaging	Console App	.NET 8.0	RabbitMQ subscriber for outbound email dispatch via AWS SES
SmsMessaging	Console App	.NET 8.0	RabbitMQ subscriber for outbound SMS via AWS Pinpoint
PushMessaging	Console App	.NET 8.0	RabbitMQ subscriber for push notifications via AWS SNS
Unity.Notifications.DAL	Library	.NET 8.0	Data access layer (SQL Server + DynamoDB)
Unity.Notifications.Messaging	Library	.NET Standard 2.0 / .NET 4.5 / .NET Standard 2.1	Shared contracts/models (published as NuGet v1.12.0)
Unity.Notifications.SqlServer	Console App	.NET 8.0	DbUp database migration tool
EmailDecryptor	Console Tool	.NET 8.0	Email message decryption utility
TestEmailSender	Console Tool	.NET 9.0	Test email sending utility

Test Projects

Project	Type	Description
Unity.Notifications.Web.Test	NUnit (.NET 8.0)	Web API tests
EmailMessaging.Test	NUnit (.NET 8.0)	Email subscriber tests
SmsMessaging.Test	NUnit (.NET 8.0)	SMS subscriber tests
PushMessaging.Test	NUnit (.NET 8.0)	Push subscriber tests
Notifications.IntegrationTests	NUnit (.NET 8.0)	End-to-end integration tests

Architecture

Purpose

Unity Notifications is the centralized notification delivery platform for the TELS ecosystem. It provides a unified interface for sending communications across three channels:

Email — Outbound email via AWS SES (Simple Email Service), with attachment storage in S3, message encryption support, and bounce/complaint handling via SNS webhooks.
SMS — Outbound SMS via AWS Pinpoint, with inbound message handling, delivery receipts, phone number preference management (opt-in/opt-out), and conversation history tracking.
Push Notifications — Mobile push notifications via AWS SNS (Simple Notification Service).

The service follows an event-driven architecture: upstream services publish message envelopes to RabbitMQ, and three dedicated subscriber services (email, SMS, push) consume and deliver them through their respective AWS channels.

Layering Pattern

┌─────────────────────────────────────────────────────┐
│  API (Unity.Notifications.Web)                       │
│  EmailController — attachment upload, validation,    │
│                     bounce handling                   │
│  HomeController — SMS inbound, delivery receipts,    │
│                    preferences, conversation history  │
│  PinpointController — AWS Pinpoint webhooks          │
│  DiagnosticsController — health check                │
├─────────────────────────────────────────────────────┤
│  Shared Contracts (Unity.Notifications.Messaging)    │
│  OutboundEmailEnvelope, OutboundSMS,                 │
│  MobilePushNotification, InboundSMS,                 │
│  DeliveryReceiptSMS, OutboundEmailBounced            │
├─────────────────────────────────────────────────────┤
│  Subscribers (3 independent consumer services)       │
│  EmailMessaging → AWS SES                            │
│  SmsMessaging → AWS Pinpoint                         │
│  PushMessaging → AWS SNS                             │
├─────────────────────────────────────────────────────┤
│  DAL (Unity.Notifications.DAL)                       │
│  SQL Server (SMS data) + DynamoDB (email audit)      │
└─────────────────────────────────────────────────────┘

Data Access

SQL Server: Dapper 2.0.123 — SMS messages, delivery receipts, phone preferences
DynamoDB: AWS SDK — Email sent audit trail (unity-notifications-ses-email-sent table)
S3: Email attachment storage
Migrations: DbUp via Unity.Notifications.SqlServer project

Message Queue Integration

Broker: RabbitMQ via MassTransit 7.3.1
Consumers: 3 (EmailMessaging, SmsMessaging, PushMessaging)
Published Events: InboundSMS, DeliveryReceiptSMS, OutboundEmailBounced
Delivery Fallback: BusProxy (S3 fallback) for outbound publishing

Key Features

1. Email Delivery Pipeline

Consuming services publish OutboundEmailEnvelope to RabbitMQ
EmailMessaging subscriber decrypts (if encrypted), validates, and sends via AWS SES
Attachments stored in S3 bucket, referenced by content path
Message encryption via RSA public key + signature validation
DynamoDB audit trail records sent emails with message tags
SNS bounce webhook → API publishes OutboundEmailBounced event

2. SMS Messaging

Outbound SMS via AWS Pinpoint (E.164 format)
Inbound SMS handling via Pinpoint SNS webhook and legacy Vonage/Nexmo webhook
Delivery receipt processing (Pinpoint Firehose and Vonage)
Phone number preference management (opt-in/opt-out tracking)
Conversation history with message part concatenation
Status tracking: Delivered, Expired, Failed, Rejected, Accepted, Buffered

3. Push Notifications

Mobile push via AWS SNS
Application-specific routing
Badge count support
Extra information dictionary for custom payload

4. Message Encryption

RSA public key encryption for sensitive email content
Signature validation per application code
EmailDecryptor tool for troubleshooting

API Surface

4 controllers exposing 12 endpoints:

Authentication

Email/Pinpoint endpoints: SharedSecret validation via custom headers (x-unity-timestamp, x-unity-verificationcode)
SMS endpoints: Mixed — some require JWT Bearer, some use SharedSecret
Pinpoint webhooks: AWS SNS signature validation or Firehose access key
Diagnostics: Anonymous

See API Documentation for full endpoint details.

Key Technology Stack

Category	Technology
Runtime	.NET 8.0
Web Framework	ASP.NET Core 8.0
Data Access	Dapper 2.0.123 (SQL Server), AWS DynamoDB SDK
Database	SQL Server (SMS data), AWS DynamoDB (email audit)
Messaging	RabbitMQ + MassTransit 7.3.1
Email Delivery	AWS SES v2, MailKit 4.7.1.1 (local dev)
SMS Delivery	AWS Pinpoint
Push Delivery	AWS SNS
Object Storage	AWS S3 (email attachments)
Resilience	Polly 6.0.3 (SMS retries)
Phone Validation	libphonenumber-csharp 8.12.57
API Docs	Swashbuckle 6.3.0
Monitoring	New Relic 10.28.0, NLog (JSON → CloudWatch)
Bus Fallback	TELS.BusProxy.Client 2.1.5 (S3 fallback)
Testing	NUnit 3.13.3, Moq 4.17.2, Mountebank

Deployment

Docker Containers

Unity.Notifications.Web — API (port 7169)
EmailMessaging — Email subscriber
SmsMessaging — SMS subscriber
PushMessaging — Push subscriber

Environments

Environment	URL
Local	http://localhost:7169
DEV	https://devunitynotifications.directs.com
QA	https://qaunitynotifications.directs.com
PROD	https://unitynotifications.directs.com

CI/CD Pipeline

Stage	Jobs
Build	dotnet build, docker buildx (multi-platform: arm64, amd64)
Test	Unit + integration tests
Push	DbUp to Octopus, contracts to ProGet
Deploy	Terraform per environment (sandbox, testing, production)

Infrastructure

Platform: AWS ECS (multi-arch: arm64, amd64)
Secrets: HashiCorp Vault + Envconsul
Monitoring: CloudWatch + NLog (JSON), SumoLogic, New Relic APM
IaC: Terraform (modules: api, email-subscriber, push-subscriber, sms-subscriber, ALB, Route53, ECS, database)
Container Versioning: 1.10.{CI_PIPELINE_ID}

Configuration

Configuration Group	Key Variables
Auth	JWT Bearer validation settings
Database	SQL Server connection string
Email	AWS SES config, S3 attachment bucket, sender credentials (Vault)
SMS	AWS Pinpoint config, sender IDs, blacklisted/restricted numbers
Push	AWS SNS configuration
Messaging	RabbitMQ host, username, password
Endpoints	Auth service URL for token validation
BusProxy	BusProxy client config for event publishing

External Integrations

Integration	Mechanism	Description
AWS SES	SDK (SimpleEmailV2)	Outbound email delivery
AWS Pinpoint	SDK + SNS Webhooks	Outbound SMS, inbound SMS, delivery receipts
AWS SNS	SDK	Push notification delivery, email bounce notifications
AWS S3	SDK	Email attachment storage
AWS DynamoDB	SDK	Email sent audit trail
Auth Service	HTTP API (JWT)	Token validation for protected endpoints
BusProxy	HTTP API (NuGet client)	Event publishing with S3 fallback
RabbitMQ	MassTransit	Message consumption and publishing

NuGet Packages Published

Package	Target	Published To
Unity.Notifications.Messaging	.NET Standard 2.0 / 2.1 / .NET 4.5	ProGet

Key Files & Locations

API: - Unity.Notifications.Web/Controllers/ — 4 controllers - Unity.Notifications.Web/Startup.cs — Service configuration

Subscribers: - Unity.Notifications.Messaging.Consumers/Email/ — Email consumer + SES sender - Unity.Notifications.Messaging.Consumers/Sms/ — SMS consumer + Pinpoint sender - Unity.Notifications.Messaging.Consumers/Push/ — Push consumer + SNS sender

Contracts: - Unity.Notifications.Messaging/ — Shared message contracts

Data Access: - Unity.Notifications.DAL/ — SQL Server + DynamoDB providers - Unity.Notifications.SqlServer/ — DbUp migrations

Notes

Multi-target contracts: The Messaging library targets .NET Standard 2.0, .NET Standard 2.1, AND .NET Framework 4.5 for maximum consumer compatibility (including legacy .NET Framework services).
Message encryption: Email content can be RSA-encrypted with per-application keys. The EmailDecryptor tool assists with troubleshooting encrypted messages.
SMS delivery states: Tracks 8 status codes (Delivered, Expired, Failed, Rejected, Accepted, Buffered, Unknown, Historical) and 16 error codes.
Local development: Uses LocalStack for S3/DynamoDB simulation, MailKit for SMTP (drops .eml files to filesystem).
Vonage/Nexmo legacy: The HomeController still supports legacy Vonage webhook format alongside AWS Pinpoint webhooks.
Phone number blacklisting: Configurable restricted and blacklisted delivery numbers stored in Vault secrets.
The service uses an older version of MassTransit (7.3.1) compared to other TELS services (8.2.5).