Technical solution design

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. Container diagram

This diagram shows the platform services involved in implementing the requirements and the interaction between them.

2. Involved services and their purpose within the design of the solution

This section provides a list of system components that are involved or need to be changed/created as part of the implementation of functional requirements according to the technical design of the solution.

Component	Official title	Purpose
Registry regulation	registry-regulation	Setting up templates for sending notifications by communication channels
Regulation publication pipeline	jenkins	Publishing changes to message templates to the target registry environment
Notifications template publisher	notification-template-publisher	Preparation and uploading of notification templates from the regulation repository to a separate template repository for use in script execution
Platform administration interface	control-plane-console	Setting available communication channels for the target environment of the registry
Registry creation pipeline	control-plane-jenkins	Application of communication channel settings to the registry’s target environment
User and access management service	keycloak	Receiving user attributes by identifier (RNOKPP)
Citizen portal	citizen-portal	Viewing in-app notifications in the inbox of the Citizen portal
Business process execution service	bpms	Formation and publication of an event about the need to send a message to users during the execution of a business process
User notification service	notification-service	Responding to events about the need to send a notification to users by generating a notification based on the specified template and input data with subsequent sending depending on the specified and pre-configured communication channel. Manage notification templates.
User settings management service	user-settings-service-api	Receiving settings of communication channels selected by users for receiving notifications
Platform mail server	platform-mail-server	Mail server that is distributed with the platform for interoperability by registries as a default option
External mail server	external-mail-server	Mail server chosen by the registry administrator in case of special requirements for sending mail messages
Diia notification service (citizen-facing solution)	diia-notification-service	Sending push notifications to Diia mobile application
Distributed relational database Citus	citus-master	Long-term storage of notification templates on the target registry environment. Storage of in-app user notifications.
Distributed message broker Kafka	kafka	Exchange of notifications between components of the registry management system

Component

Official title

Purpose

Registry regulation

registry-regulation

Setting up templates for sending notifications by communication channels

Regulation publication pipeline

jenkins

Publishing changes to message templates to the target registry environment

Notifications template publisher

notification-template-publisher

Preparation and uploading of notification templates from the regulation repository to a separate template repository for use in script execution

Platform administration interface

control-plane-console

Setting available communication channels for the target environment of the registry

Registry creation pipeline

control-plane-jenkins

Application of communication channel settings to the registry’s target environment

User and access management service

keycloak

Receiving user attributes by identifier (RNOKPP)

Citizen portal

citizen-portal

Viewing in-app notifications in the inbox of the Citizen portal

Business process execution service

bpms

Formation and publication of an event about the need to send a message to users during the execution of a business process

User notification service

notification-service

Responding to events about the need to send a notification to users by generating a notification based on the specified template and input data with subsequent sending depending on the specified and pre-configured communication channel. Manage notification templates.

User settings management service

user-settings-service-api

Receiving settings of communication channels selected by users for receiving notifications

Platform mail server

platform-mail-server

Mail server that is distributed with the platform for interoperability by registries as a default option

External mail server

external-mail-server

Mail server chosen by the registry administrator in case of special requirements for sending mail messages

Diia notification service (citizen-facing solution)

diia-notification-service

Sending push notifications to Diia mobile application

Distributed relational database Citus

citus-master

Long-term storage of notification templates on the target registry environment. Storage of in-app user notifications.

Distributed message broker Kafka

kafka

Exchange of notifications between components of the registry management system

3. Configuring interservice interaction policies

For the correct operation of the notification subsystem, appropriate network policies NetworkPolicy must be configured, which allow interaction for the following components:

kong → notification-service
bpms → kafka
notification-service → kafka
notification-service → keycloak
notification-service → user-settings-service-api
notification-service → citus-master
notification-service → kafka-schema-registry
notification-service → platform-mail-server

Depending on the selected configuration at the stage of creating/editing registry settings, a ServiceEntry will be automatically created to configure access to external services at the Istio Service Mesh level:

notification-service → external-mail-server

This functionality is specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions. Please consult the local guidelines or documentation if you are implementing this outside Ukraine.

notification-service → diia-notification-service

4. Kafka topics of requests for sending notifications to users

Currently, the following Kafka-topics, segregated by purpose, scaling requirements, and load control for downstream-services, are responsible for servicing requests to send messages to users:

Official title

Description

user-notifications

Publication and processing of system requests for sending messages to users. Implements asynchronous interaction between registry services and User notification service

user-notifications.DLT

Publication of requests for sending messages to users that could not be processed by the User notification service

email-notifications

Publication and processing of requests to send mail notifications to users through a platform or external SMTP server

email-notifications.DLT

Publication of requests for sending mail notifications to users that could not be processed

diia-notifications (citizen-facing solution)

Publication and processing of requests for sending push-notifications to users in the mobile application Diia

diia-notifications.DLT (citizen-facing solution)

Publication of requests to send push notifications to users in the Diia mobile application that could not be processed

inbox-notifications

Publication and processing of requests for sending notifications to users in Citizen portal

inbox-notifications.DLT

Publication of requests for sending notifications to users in Citizen portal that could not be processed

4.1. Publication and processing of system requests for sending notifications

List of Kafka-topics:

user-notifications
user-notifications.DLT

The canonical view of the notification structure

{
  "context": {
    "system": "Low-code Platform",
    "application": "<bpms.app.name>",
    "businessProcess": "<optional>",
    "businessProcessDefinitionId": "<optional>",
    "businessProcessInstanceId": "<optional>",
    "businessActivity": "<optional>",
    "businessActivityInstanceId": "<optional>"
  },
  "notification": {
    "templateName": "<notification template unique name>",
    "ignoreChannelPreferences": "<true|false (default: false) - ignore whether channel is active or not - used for OTP verification, etc. >"
  },
  "recipients": [
    {
      "id": "<User`s ID>",
      "channels": [
        {
          "channel": "diia",
          "rnokpp": "<User's taxpayer code>"
        },
        {
          "channel": "email",
          "email": "<User`s Email>"
        }
      ],
      "parameters": [
        {
            "key": "<key>",
            "value": "<value>"
        }
      ]
    }
  ]
}

diia channel is specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions.

Please consult the local guidelines or documentation if you are implementing this outside of Ukraine.

Ukrainian implementation example

{
  "channel": "diia",
  "rnokpp": "<User's taxpayer code>"
}

4.2. Publication and processing of requests to send notifications to users in Citizen portal

List of Kafka-topics:

inbox-notifications
inbox-notifications.DLT

The canonical view of the notification structure

{
  "context": {
    "system": "Low-code Platform",
    "application": "<bpms.app.name>",
    "businessProcess": "<optional>",
    "businessProcessDefinitionId": "<optional>",
    "businessProcessInstanceId": "<optional>",
    "businessActivity": "<optional>",
    "businessActivityInstanceId": "<optional>"
  },
  "notification": {
    "subject": "<notification subject>",
    "message": "<notification message>"
  },
  "recipient": {
    "id": "<User ID>"
  }
}

4.3. Publication and processing of requests for sending Email notifications

List of Kafka-topics:

email-notifications
email-notifications.DLT

The canonical view of the notification structure

{
  "context": {
    "system": "Low-code Platform",
    "application": "<bpms.app.name>",
    "businessProcess": "<optional>",
    "businessProcessDefinitionId": "<optional>",
    "businessProcessInstanceId": "<optional>",
    "businessActivity": "<optional>",
    "businessActivityInstanceId": "<optional>"
  },
  "notification": {
    "subject": "<notification subject>",
    "message": "<notification message>"
  },
  "recipient": {
    "id": "<User ID - optional>",
    "email": "<User Email>"
  }
}

4.4. Publishing and processing requests for sending push-notifications to the mobile application Diia

List of Kafka-topics:

diia-notifications
diia-notifications.DLT

The canonical view of the notification structure

{
  "context": {
    "system": "Low-code Platform",
    "application": "<bpms.app.name>",
    "businessProcess": "<optional>",
    "businessProcessDefinitionId": "<optional>",
    "businessProcessInstanceId": "<optional>",
    "businessActivity": "<optional>",
    "businessActivityInstanceId": "<optional>"
  },
  "notification": {
    "templateName": "<template name>",
    "externalTemplateId": "<external template id>"
  },
  "recipient": {
    "id": "<User ID - optional>",
    "rnokpp": "<User's taxpayer code>",
    "parameters": [
      {
        "key": "<key>",
        "value": "<value>"
      }
    ]
  }
}

4.5. General settings of Kafka topics of the notification subsystem

4.5.1. Setting up target topics of requests for sending notifications

Property	Value	Description
num-partitions	1	The number of sections within a topic to save notifications
replication-factor	1	The number of replicas of the target topic
retention-policy-in-days	7	The number of days to keep a message in Kafka

Property

Value

Description

num-partitions

The number of sections within a topic to save notifications

replication-factor

The number of replicas of the target topic

retention-policy-in-days

The number of days to keep a message in Kafka

4.5.2. Setting Dead-Letter-Queue of request topics for sending notifications that could not be processed

A service topic that is used to publish and temporarily save events of requests to send notifications to users that could not be processed for the purpose of reprocessing them later.

Property	Value	Description
num-partitions	1	The number of sections within a topic to save notification
replication-factor	1	The number of replicas of the target topic
retention-policy-in-days	7	The number of days to keep a notification in Kafka

Property

Value

Description

num-partitions

The number of sections within a topic to save notification

replication-factor

The number of replicas of the target topic

retention-policy-in-days

The number of days to keep a notification in Kafka

Viewing and monitoring of failed events is possible through a separate kafka-ui web interface.

If it is necessary to send events to the administrator for reprocessing, the option of building a separate service process based on Kafka Connect, which will transfer events from the Dead-Letter-Queue to the target topic, is being considered.