Engine

Introduction

FanX Rules Engine is a events processing unit that is responsible for executing and managing user-defined rules.

The Rules Engine processes incoming events without requiring any aggregation or data preprocessing. It does not directly communicate with any internal or external data provider, instead, events should be published to the message broker, which Rules Engine will consume.

Event

The UserEvent struct represents an event that is processed by the Rules Engine. It should always contain the following fields:

Field	Type	Description
id	UUID	The unique event identifier.
clientId	String	The identifier of the client associated with the event.
createdAt	DateTime	The timestamp when the event was created.
sourceSystem	String	Event source system.
sourceSystemId	String	Event type (unique per source system).
authId	Integer	Target user id.
data	Object	Data associated with the event.

{
    "id": "c7a18952-b7ce-4fdc-8017-ed5bbddbf745",
    "clientId": "ICPRODUCT",
    "createdAt": "2024-05-09T12:16:39.02799841Z",
    "sourceSystem": "polls-service",
    "sourceSystemId": "poll-submitted",
    "authId": 14659917,
    "data": {
        "pollId": "c828978e-d9aa-4ea0-8b05-19d3b3f71b08",
        "optionId": "eecc6959-6082-4cda-a5ca-fa08614773ac",
        "language": "en",
        "originUrl": "https://fanx.incrowdsports.io/demo-poll",
        "submittedAt": "2024-05-09T12:16:21.01541241Z"
    }
}

Sample event produced by a Polls Service

Ordering

Rules Engine allows parallel events processing and relies on internal ordering implementation to make it work. KCL ensures that events with the same authId will preserve their order, making sure that user events will be processed sequentially.

If custom producer is being used, it is responsible for implementing consistent ordering mechanism. Please refer to 'Message Broker' section for more context.

Deduplication

In order to avoid duplicates processing, Rules Engine will skip any event that already resulted progress change. This means that events producer is responsible for making sure that event generated by a specific action will have consistent id on retry.

Scheduling

KCL offers messages scheduling (supports event and transaction entities) mechanism that can be used to produce event on a specific time. Scheduler has 60 seconds precision window, so the event is guaranteed to be produced within 60 ticks after the target scheduled timestamp. Please refer to 'KCL - Scheduling' for more details and use cases.

Flow

Flow is the essential part of Rules Engine. It is a user-defined rule that is executed every time any event satisfies rule's conditions.

Field	Type	Description
id	UUID	The unique identifier of the flow.
clientId	String	The identifier of the client associated with the flow.
parentId	UUID?	The identifier of the parent flow, if any.
points	Integer?	The points associated with the flow.
experience	Integer?	The experience associated with the flow.
rewards	Array<String>	The rewards associated with the flow.
enabled	Boolean	Indicates whether the flow is enabled or not.
name	String	The name of the flow.
description	String	The description of the flow.
sourceSystem	String?	The source system of the flow.
sourceSystemId	String?	The source system ID of the flow.
driver	Driver?	The driver of the flow.
replicas	Integer	The number of replicas of the flow.
cooldownTimeout	Integer?	The cooldown timeout of the flow.
resetThreshold	Integer?	The reset threshold of the flow.
maxCompletions	Integer	The maximum number of completions of the flow.
validFrom	DateTime?	The valid from date of the flow.
validTo	DateTime?	The valid to date of the flow.
schema	Schema?	The schema of the flow.
dependencies	Map<Boolean, UUID>	The dependencies of the flow.
hooks	Array<Hook>	The hooks associated with the flow.
metadata	Any	The metadata of the flow.

? - optional field

In order to satisfy the flow, target event should have matching sourceSystem and sourceSystemId fields.

GFlow

In order to avoid fetching all target flows when event received, Rules Engine implements in-memory graph database that provides low-latency retrieval for all active flows. Flow is treated as valid if:

• validFrom and/or validTo fields are not set or are in current timerange
• enabled is set to true

Please note that GFlow is caching flows, so flow changes can take up to 5 minutes (configurable per-client) to take affect. Clients should avoid updating live production flows as this may result unexpected behaviour.