Notifications

This is NOT about HTML Notification API.

This is about designing a service to provide clients with notifying its users. It's about the production and the delivery of messages to users, or other clients, and not the display per se.


There are many ways to communicate digitally. Short Message Service (aka SMS), (automated) phone services, emails, push notifications, mobile apps, all can be used to reach out to people and/or software clients. From now on, I'll use the term "user" to refer to both human and computer clients.

Why?

I'm a big fan of not reinventing the wheel, and avoiding technical debt. But sometimes (often), third party solutions are either not enough, too young or unreliable. The idea here is to design something simple that can leverage third party solutions but robust enough to be able to provide any required feature missing from third parties.

For example, as of today, AWS SNS provides SMS notifications, but only from AWS to phone users and not the other way around. Mobile Push Notifications are not HIPAA compliant. AWS doesn't provide custom subscription/un-subscription messages.
The list goes on but what's important is the logic that comes right before using any third party services: that logic must be implemented anyway. Be it loading templates, gathering data to substitutes variables in the template, something usually happens before even doing the actual notification.

Features

The first feature of such service is "polite-ness", providing support for clients to let their users to subscribe and unsubscribe to certain notifications.

The second feature is to host templates for software clients. This takes the burden off the client to design and store that data.

The third feature is to allow for third party integration. This is done by basically providing implementations and configurations to media defined by user to get notifications (email, SMS, etc.).

Architecture

Here's a very simple class diagram of what we need to represent to support such notification service.

Such model allows for extensions and more complex notification system can be built upon it.

MediumType

This represents all the different medium types a user can get notifications with.
For example, Apple Push Notification Service (apns), Amazon Device Messaging (adm), Google Cloud Messaging (gcm), Microsoft Push Notification Service (mpns), Windows Notification Service (wns) and more.

SubscriptionStatus

This represents the actual status of a recipient's subscription to a topic.

• normal simply means user is willing to receive notifications. 
• pending means user has yet to confirm his/her subscription
• blocked means user explicitly unsubscribed to topic (or turned down invitation or subscription request)
• bounced means notification have bounced (for emails).

Template

Template represents the actual message of the notification. This most likely contain variables and therefore this system will require some engine to at least provide some reduction. A more advanced engine could provide scripting within the template to handle more complicated cases without having to tweak the core of the system.

A topic can have different templates:
Subscription/Confirmation, prompting user to confirm the subscription
Un-subscription Confirmation, acknowledging the system successfully unsubscribed user from any notifications to given topic from this moment on.
Notification, being the actual message(s) related to the topic (e.g. announcement, alerts, etc.)

Topic

A topic represents the channel users can subscribe to to receive notifications. This is very similar to AWS SNS Topic and plays a very similar role.
Certain topics might be "auto-subscribed", where users don't need to explicitly subscribe to the topic, and might not even be able to unsubscribe from those. Examples are security notifications (password expired, logged in from different location, etc.) or maintenance (planned outages, etc.).
In this case, the system need to figure out which medium to use to notify users. One way is to set a default medium for each medium type (e.g. default/primary email address) and use this to send messages to.
It's up to the client to respect its users and their preferences, but in those exceptional cases (security, maintenance) it makes sense to not let user opt-in or even out of such notifications.

TopicMediumSetting

This represent the necessary configuration to deliver notification for a given medium. This might be some certificates or tokens to use to send notifications through a third party service.

Recipient

A Recipient represents the entity engaged in notifications. At this level it's just an internal identifier and an external one. The media to be used to notify this recipient are specified in RecipientMedium.

This model allows for deploying a notification micro service by leveraging an existing identity management service for example.

RecipientMedium

This represents the medium made available by user to receive notifications.
A default medium might be specified as mentioned earlier to allow for certain notifications, like alerts or security related messages.

RecipientSubscription

This represents the actual subscription of a user to a topic using a certain medium to get notified on.
Its status will determine whether or not a message will be sent to the user.

Conclusion

A notification application lends itself well as a micro-service.
Being self-contained (especially when duplicating data in the recipient entity), it can function independently from other services.
I omitted some aspects, namely handling (email) bounces, spam flags and implementing servlets for opt-outs and such. Those may not be trivial, and are certainly necessary, but won't change much in this core architecture.