Skip to content

Event Processing Pipeline

This document describes the event processing pipeline in BotFlux — the path an incoming user message follows until a response is formed and delivered to the platform.

The document is intended for developers using BotFlux to build bots and dialog systems and describes the architectural roles of components without reference to any specific platform.

Purpose of the pipeline

The event processing pipeline addresses the following concerns:

  • isolation of business logic from transport and platform layers
  • a unified and extensible mechanism for processing incoming events
  • centralized error handling and recovery
  • extensibility without modifying existing handlers

The pipeline is an infrastructure mechanism and does not contain business logic.

Overview

Event processing passes through the following logical stages:

  1. Receiving a message by the transport
  2. Event transformation by the gateway
  3. Processing orchestration by the dispatcher
  4. Construction of handler invocation arguments
  5. Execution of business logic
  6. Conversion of the result into an action
  7. Delivery of the action to the platform
  8. Handling execution results and errors

The full processing cycle is illustrated by the following sequence diagram:

sequenceDiagram
    actor U as User

    box Infrastructure
    participant T as Transport
    participant G as Gateway
    end

    box Pipeline Dispatcher
    participant D as Dispatcher
    participant AR as Argument resolver
    participant AC as Action converter
    participant EH as Exception handler
    end

    participant H as Handler

    U-->>T: Message
    T->>G: Platform event
    G->>D: Gateway event
    D->>AR: Event context
    AR->>H: Invocation arguments
    H->>AC: Result
    AC->>D: Action
    D-->>EH: Recoverable error
    EH-->>D: Recovered action
    D->>G: BotFlux action
    G->>T: Platform request
    G->>D: Perform action result
    D-->>EH: Failure
    T-->>U: Message

Pipeline participants

Transport

Transport is an external infrastructure component responsible for interacting with the message delivery platform.

Primary responsibilities:

  • receiving incoming requests (HTTP, WebSocket, Long Polling, etc.)
  • sending outgoing requests to the platform
  • absence of business logic

Transport does not participate in event processing and does not make decisions.

Gateway

Gateway acts as an adapter between a specific platform and the BotFlux core.

Primary responsibilities:

  • transforming platform-specific events into Gateway Events
  • transforming BotFlux Actions into platform requests
  • managing queues and asynchronous delivery

Gateway does not contain business logic and does not process events directly.

Dispatcher

Dispatcher is the central coordinator of the event processing pipeline.

Primary responsibilities:

  • managing the order of event processing
  • invoking argument resolvers
  • invoking handlers
  • passing results to action converters
  • delegating error handling

Dispatcher does not contain business logic and does not interpret handler results.

Argument Resolver

Argument Resolver is an infrastructure component responsible for constructing handler invocation arguments.

Primary responsibilities:

  • receiving the Event Context
  • extracting data from the event
  • forming parameters for handler invocation

Argument Resolvers are used as an extensible chain and are independent of business logic.

Handler

Handler contains the application business logic.

Characteristics:

  • receives prepared arguments
  • is independent of platform and transport
  • returns an execution result
  • does not send messages directly

Handler does not manage lifecycle and does not handle delivery errors.

Action Converter

Action Converter transforms the handler execution result into a BotFlux Action.

Primary responsibilities:

  • supporting different return types
  • isolating business logic from action formats
  • enabling extensibility without modifying Dispatcher and Handler

Exception Handler

Exception Handler is responsible for processing exceptions that occur during event handling.

Capabilities:

  • intercepting exceptions at any stage of the pipeline
  • recovering execution
  • converting an error into an action
  • propagating exceptions further

Exception Handlers do not affect handler business logic.

Event processing flow

  1. A user sends a message to the platform
  2. Transport receives the message and passes it to the Gateway
  3. Gateway transforms the message into a Gateway Event
  4. Dispatcher initiates event processing
  5. Argument Resolver constructs invocation arguments
  6. Handler executes business logic
  7. Action Converter transforms the result into a BotFlux Action
  8. Dispatcher passes the action to the Gateway
  9. Gateway sends the platform request via Transport
  10. Execution results and delivery errors are handled by Dispatcher and Exception Handler

Architectural guarantees

The event processing pipeline provides:

  • strict layer isolation
  • extensibility without contract violations
  • centralized error handling
  • a predictable and repeatable processing lifecycle

This approach enables system evolution without rewriting existing handlers or platform adapters.