# 1 - Summary
A publish/subscribe (pub/sub), asynchronous (async) communication mechanism for the BriteCore platform.
# 2 - Purpose
BriteEvents provides a highly scalable and available service for publishing a large volume of events across the entire platform. The events being published are subscribable, so that any other BriteCore service or authenticated third party can respond to any event however it needs to.
Asynchronous event messaging is a pillar for service-oriented architectures. It helps decouple services, which not only speeds up development, but also means that services can launch in a more modular manner.
By exposing BriteEvents on the API, a pub/sub model is available for extending BriteCore’s behavior into other systems. This is an incredible point of extensibility and customization.
There will be many services, such as BriteRules, BriteDelivery and BriteFlow that rely heavily on BriteEvents and add yet another layer of abstraction and specialization on top of responding to system events.
# 3 - Concepts
# 3.1 - Topics
Topics are the “definition” of an event. They describe what an event will look like once it is published. By defining topics up front, we enable discovery and documentation of our events before any events have been published to the system.
# 3.1.1 - Category
The category of the topic is a broad term to enable filtering and grouping. This generally aligns with the name of the service that creates the topic. Examples include “policies”, “claims”, “lines”.
# 3.1.2 - Entity
The entity of the topic is the type of entity being acted on, and serves to standardize topic naming conventions. Examples include “Policy”, “Claim”, “Line”.
# 3.1.3 - Action
The action of the topic is the past-tense verb describing what was done to the entity, and serves to standardize topic naming conventions. Examples include “Created”, “Updated”, “Deleted”.
# 3.1.4 - Description
The description of the topic is a human-readable summary of the topic that is used for searching. It should include key terms that relate to the event. Example: “An existing policy renewed successfully."
# 3.1.5 - Schema
The schema of the topic is a json-schema document that outlines the shape of the events. This allows a similar contract to an API specification, such that subscribers know exactly what data to expect and how it will be formatted.
# 3.2 - Subscriptions
Subscriptions are created by other services or authenticated API users in order to express an interest in a topic. When an event is sent to a topic, all subscriptions to that topic will be notified.
Note that Category, Entity, and Action may seem redundant or verbose. The reason these must be specified instead of perhaps a Topic ID, is so that subscriptions can be created before the topic might exist. This allows services to be launched in arbitrary order or have circular references between services.
# 3.2.1 - Category
The category of the subscription should match the category of the topic that it wishes to subscribe to.
# 3.2.2 - Entity
The entity of the subscription should match the entity of the topic that it wishes to subscribe to.
# 3.2.3 - Action
The action of the subscription should match the action of the topic that it wishes to subscribe to.
# 3.2.4 - Description
The description of the subscription is a human-readable summary of the subscription that is used for searching. It should include key terms that relate to the subscription. Example: “Generate a Declaration whenever a policy renews”
# 3.2.5 - Protocol
The protocol of the subscription specifies how the event will be delivered to the interested party. The product should be architected such that this list of available protocols is extensible. Version 1 (MVP) should support the following protocols:
- AWS Lambda
- AWS SQS Queue
# 3.2.6 - Endpoint
The endpoint of the subscription specifies where the event will be delivered for the interested party. The format of the endpoint will vary depending on the protocol. Corresponding to the above list of protocols, here are some examples of endpoints: