Architecture

The Citeck platform is built on a microservice event-driven architecture, which provides horizontal scalability, independent component deployment, and flexibility when integrating with external systems. Each microservice is responsible for its own domain: data model management, business processes, notifications, content transformation, and other functions. The primary method of communication between microservices is message exchange through a broker (RabbitMQ), as well as REST API.

The platform supports working with various data sources without needing to copy data into an internal repository. Data access uses its own query language Records API. The list of data sources can be easily extended.

System components:

• DAO services – сервисы работы с контентом и метаданными. В качестве источников данных могут использоваться Базы данных, 1С, SAP и другие;

• Process services – business process management services supporting BPMN process modeling notation;

• Application services – services for managing Citeck applications, their versioning and deployment;

• Data services – data processing services, including data validation and indexing;

• Integration services – integration services, including legally significant document exchange (EDI);

• API gateway – API gateway, used among other things for requests from the user interface (web and mobile);

• Business logic services – business logic and configuration services.

The system interface is built on the ReactJS framework as static JS libraries that are served via NGINX and run in web browsers on user devices.

The mobile interface is built on the React Native framework; responsive layout for mobile browsers is also supported.

Requests from user interfaces are routed through NGINX and the API gateway.

Citeck software is deployed using Docker / Kubernetes containerization services.

Microservices

Component	Description
ecos-proxy	Container with nginx (OpenResty) and UI static assets (JS + CSS).
ecos-gateway	Microservice implementing the API gateway for client-to-server communication.
ecos-apps	Citeck applications microservice responsible for delivering Citeck applications to target services.
ecos-notifications	Notification sending microservice (email, push notifications, etc.).
ecos-model	Models microservice. Responsible for information about types, numbering templates, and permissions matrices.
ecos-history	History storage microservice. Subscribed to system events and saves information about them to the database.
ecos-process	Process microservice. Responsible for BPMN processes.
ecos-eis	Keycloak application for system authentication.
opensearch	Система индексации контента документов.
ecos-uiserv	UI configurations microservice. Responsible for forms, journals, UI actions, themes, dashboards, localization, icons, and menu configuration.
ecos-integrations	Microservice for integration with external systems (SAP, 1C, Rabbit MQ, etc.).
ecos-transformations	Microservice for content transformation. For example, template-based generation, document type conversion, stamp application, etc.
ecos-content	Микросервис для обеспечения хранения файлов в системе в определенное файловое хранилище (S3).
zookeeper	Distributed key-value store for coordinating Citeck applications with each other.
Rabbit MQ	Application for message exchange between microservices.

Data Storage

1. The primary relational database used is PostgreSQL.

2. Хранение метаданных поддерживается в любой системе через адаптер (record source). Существующие адаптеры: PostgreSQL, Oracle DB, MS SQL, Mongo DB, SAP HANA.

3. Для хранения документов может быть использована БД PostgreSQL, S3 -совместимое хранилище или внешняя ECM система через адаптер (например, разработан адаптер к системе OpenText).

4. Помимо баз данных используется также прямая запись в файловую систему для приложений Zookeeper, Rabbit MQ и OpenSearch.

Component Dependencies

1. The central part of the Citeck system is the <DATA SOURCE> abstraction, which can be any data source in any of the Citeck microservices.

   To add new sources, it is sufficient to implement a specific interface, and the data from that source can be freely integrated with the entire Citeck ecosystem (it can be displayed in journals, edited and viewed through forms, used to send notifications, start processes, etc.).

Any <DATA SOURCE> can generally communicate with the following services:

• ecos-model for auto-numbering, permission delegation, and retrieving individual permission settings;

• ecos-content for working with content;

• zookeeper for working with artifact registries.

Communication with data sources is built on the universal Records API. Dependencies on <DATA SOURCE> by microservice:

• ecos-uiserv loads attributes for filtering UI actions by conditions defined in the configuration;

• ecos-notifications loads attributes for populating the notification template;

• ecos-history loads attributes for saving a record to the history;

• ecos-process loads and modifies attributes during BPMN process execution.

2. Почти все микросервисы работают с Rabbit MQ (события и команды) и с Zookeeper (события, конфигурация Citeck, реестры типов, аспектов, настроек прав, шаблонов нумерации, распределенные блокировки, внешние миксины) 3. UI (мобильный и браузерный) зависят от ecos-gateway (шлюз для доступа в систему) и от ecos-uiserv (микросервис с UI конфигурациями); 4. ecos-gateway зависит от ecos-model для получения информации по пользователям и группах, в которых они состоят. Эта информация используется для формирования JWT-токена с последующей отправкой его в остальные микросервисы для аутентификации и авторизации; 5. ecos-integrations зависит от внешних систем, с которыми настроена интеграция. 6. ecos-content зависит от места хранения контента (S3). 7. OpenSearch зависит от источников данных для индексации контента и атрибутов.

Client-Server Communication

Stage 1. When the first request arrives from the client, nginx sees that the user has no token and redirects them to Keycloak for authentication via the OpenID Connect protocol.

Stage 2. Keycloak may present a login/password prompt or immediately issue the user a token to access the system (SSO). After successful authentication, the user is redirected to the page from which they were sent to Keycloak.

Stage 3. Once the request proceeds further, ecos-gateway examines the request URL and determines which microservice should handle it (for example, the request /emodel/api/records/query should go to ecos-model).

Для получения IP адреса и порта целевого микросервиса ecos-gateway обращается в zookeper за нужной информацией и, получив её, отправляет запрос дальше.

Records API

General Description

API designed to organize simple and easily scalable communication between an information consumer and a data source. The Records API query language combines the convenience of regular REST requests in a classic REST API and the optimized, typed approach of GraphQL, where the server returns only the data the client needs with predictable typing.

Advantages of the Solution

1. Unified API for data access in the system for all consumers (Browser, Mobile application, Reporting system, Data indexing, Various microservices, Integration, etc.).

2. Support for loading data from related entities. For example, if a contract references a power of attorney, then having the contract identifier, we can retrieve any attribute of the related power of attorney.

3. Efficiency. Only the attributes needed by the consumer are loaded and computed.

4. Ease of development — the data source developer (record source) describes all attributes that consumers may request, regardless of the complexity of their computation. The consumer specifies in the request only the attributes they are interested in.

5. Ease of maintenance — API versioning is not required, as we can add new attributes at any time without touching the existing ones.

6. The type of data received is fully described by the request. From the data source we return attributes of any type, and Records API converts them to the type required by the consumer.

7. Computed attributes. The ability to add attributes that are not stored in a database or any other store, but are computed based on existing ones.

8. Поддержка объединения атрибутов из разных источников. Например, можно написать источник данных, который часть атрибутов будет брать из внешней БД, объединяя их по идентификатору.

Events

Events in Citeck allow changing the attribute set required by an event subscriber without modifying the event source.

At system startup, all subscribers register in Zookeeper the list of events they need by type and the event attributes they are interested in.

An application that can send events of this type sees that there are subscribers to these events in the system, and when they occur, prepares the required list of attributes and sends them to Rabbit MQ.

Attributes are described in the Records API format and can take advantage of all the benefits of this API.

The Citeck event system guarantees delivery of at least one message regardless of system failures.

Commands

A command is a declarative description of an action to be performed on a remote service or locally.

Commands in Citeck use RabbitMQ queues as transport. Commands can be used in both synchronous and asynchronous mode.

Command targets can be:

1. Тип сервиса (ecos-process, ecos-uiserv и др.). Команду исполняет один из инстансов данного сервиса.

2. A service instance (each service type can have many instances).

3. All service types (broadcast commands). The command source service sends a broadcast command to RabbitMQ and it is handled by all currently active services.

Applications

Citeck Applications allow exporting the required artifacts from the system in zip format and deploying them hot to another system.

An artifact is a unit of extension in Citeck. Artifacts include forms, journals, types, permissions matrices, actions, process definitions, and many other entities in the system.

The ecos-apps microservice manages artifacts, maintaining their versioning and delivering them to the target microservice. Artifact content in the system is immutable — any change to an artifact always creates a new version, while the old one is preserved in the version history.

Artifact delivery at system startup occurs in 3 stages:

1. The ecos-apps microservice, upon detecting a new microservice on the network, loads from it the list of artifact types it is interested in.

2. Having received the types, ecos-apps broadcasts a request to all other microservices to retrieve artifacts of those types.

3. After receiving the required artifacts from all microservices, ecos-apps checks whether their content has changed since the last deployment. If there are no changes, the algorithm finishes. If there are changes, the new data is deployed to the target microservice.

Artifact example. Forms journal

Architecture Description of Event-Driven Service and Business Processes

Requirements:

• Fault tolerance. If any system node fails, the system must remain operational.

• Data integrity. In the event of full or partial data loss on one of the storage nodes, data in the system must not be lost.

• Horizontal scaling. As the number of processes grows, horizontal expansion by adding more nodes to the cluster must be possible to avoid request execution time degradation as the system ages. Completed processes that finished long ago must not negatively affect active ones.

Citeck Process

The popular open-source solution Camunda is integrated as the BPM engine for business processes in ecos-process.

As a process creation and editing tool, we developed our own low-code BPMN editor based on the bpmn-js library, adding tight integration with the Citeck ecosystem (roles, forms, statuses, etc.). Developing standard processes requires no developer involvement.

Timers

Timers in ecos-process allow deferring the execution of any actions in time.

1. Any microservice in the system sends a “Create timer” command to ecos-process, specifying the timer trigger time and the command to be executed when it fires.

2. When the timer trigger time arrives, the ecos-process microservice sends the command to the target service registered in step 1. The command target can be any microservice or Alfresco.

Examples of commands: “Send email”, “Execute script”, “Complete a stage/task in a process”, etc.

Clustering

Clustering is the deployment of multiple application instances to handle high load and improve system fault tolerance.

Features:

1. Logically the system operates identically regardless of the number of application instances.

2. Application instances in a cluster typically work with the same data stores (database, file system).

3. Clustering is needed for fault tolerance and load distribution across CPU, RAM, and network.

Microservice Clustering in the Citeck System

1. To deploy a microservice cluster, we simply start multiple application instances.

2. При старте все приложения регистрируются в zookeeper, указывая при этом свой IP, HOST и PORT.

3. Балансировкой нагрузки занимается ecos-gateway. Когда приходит запрос от пользователя за некоторым ресурсом, ecos-gateway по информации в zookeeper определяет список экземпляров нужного приложения. После этого запрос уходит на один из экземпляров по алгоритму round-robin.