Architecture
Who sends, who delivers, and which identifier the notification provider uses for a staff member and for a registrant.
A product service defines what happened. The connector triggers a notification provider workflow. The notification provider decides the channel, the copy, and the inbox. The client reads that inbox. It does not send.
Novu is the default notification provider. Its install is in Novu. This page is the hop and the identity rules every notification provider has to keep.
Hops
Product service to connector
Event key, entity id, payload, recipient. In process. No HTTP from the product code itself
Connector to notification provider
Secret API key on trigger or bulk trigger. The trigger to object carries the subscriber id and any email, phone, and name
Client to notification provider
Public application identifier, subscriber id, inbox REST, and the WebSocket
Python does not list the inbox, mark a notification read, or open a WebSocket. It also does not pass channel= on send. Channel steps live on the notification provider workflow.
Send after commit
AWE collects intents inside the transaction and sends them only in flush(), after commit. discard() drops them if the transaction rolls back. Registry helpers run after session.commit(). See Implementing a send.
Registry
The helper builds the payload first. Display lookups that fail leave fields empty and still send. A registrant with no email and no phone does not send. Staff export sends to requested_by and does not call resolve_contact.
AWE
collect() does not call the notification provider. A Keycloak miss still sends. The in-app step can land without an email address.
When a send does not happen
Check these in order. The business action still succeeds in every row.
openg2p-notification is not installed
Registry and AWE return before any HTTP call
NOTIFICATION_ENABLED is false
Connector returns skipped
Event key is missing or blank in NOTIFICATION_WORKFLOWS
Connector returns skipped
Registrant contact is missing, or has no email and no phone
Registry returns before send
Export row has no requested_by
Registry returns before send
AWE engine event is not in the notify map
collect() stores nothing
AWE requester id equals source_service
Terminal events have no recipient
AWE webhook was already applied
Registry returns before the notify helpers
Notification provider rejects the trigger
Logged FAILURE or an exception. The row stays committed
The connector does not retry. The notification provider retries its own channel steps after it accepts the trigger.
Identity
Staff
Keycloak username (preferred_username)
AWE looks the user up in Keycloak at flush time. A missing profile still sends, so the in-app step can land
Registrant
person:{internal_record_id} from registrant_id()
Email and phone come from the register domain service. No email and no phone skips the send
Do not use an email address as the subscriber id. The same username on a later login is the same staff inbox. The client must pass that same id when it opens the inbox.
Registry export uses requested_by as that staff username. Change-request and intake-form events go to the registrant, not to the staff member who created the record.
Responsibilities
Business event and payload
Registry or AWE
Allow-list (NOTIFICATION_WORKFLOWS)
Deployment configuration
Trigger call
Same product service, through the connector
Workflow, template, channel, retry, inbox state
Notification provider
Email and SMS credentials
Channel integrations on the notification provider. See Email and SMS
Inbox list, unread count, mark read, live bell
Client, mounted by the staff UI
Replacing the notification provider does not change Registry or AWE call sites. Only the implementation behind the connector, and the adapter behind the client, change. See Switch provider.
Last updated
Was this helpful?