> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages.md).

# Processing Messages

This section covers how to process messages in Rumi microservices - the core of your microservice's business logic. All business logic in a Rumi microservice is written in message handlers, which are methods that the AEP Engine invokes in response to inbound messages.

## Overview

Message processing in Rumi follows a straightforward, event-driven model:

1. **Message Arrival**: An inbound message arrives on a channel that your microservice has subscribed to
2. **Duplicate Detection**: The AEP Engine checks sequence numbers to detect and discard duplicates
3. **Filtering**: Optional message filters determine if the message should be processed
4. **Handler Dispatch**: The AEP Engine dispatches the message to the appropriate handler(s) based on message type
5. **Business Logic Execution**: Your handler executes, reading the message, updating the microservice store, and creating outbound messages
6. **Transaction Commit**: When the handler returns, the AEP Engine commits the transaction, establishing consensus and sending outbound messages
7. **Message Acknowledgment**: The inbound message is acknowledged, completing the cycle

This simple model provides powerful guarantees: atomicity of store updates and message sends, exactly-once processing semantics, and automatic high availability through consensus with cluster members.

## The Message Processing Flow

Here's a visual representation of how messages flow through a Rumi microservice:

```
Inbound Message → AEP Engine → Message Handler → Transaction Commit
                      ↓              ↓                    ↓
                  Dispatch       Business           Store Updates
                                  Logic            Outbound Messages
                                                    Consensus
```

### Key Characteristics

**Event-Driven Architecture**: Your code never polls or explicitly reads from queues. Instead, you write handlers that are invoked automatically when messages arrive.

**Single-Threaded Processing**: Each microservice processes messages on a single dispatch thread, eliminating concurrency issues and maximizing CPU cache efficiency. This is a fundamental design principle that enables Rumi's performance.

**Automatic Transactions**: Every handler execution is automatically wrapped in a transaction. Store changes, outbound messages, and inbound message acknowledgment are atomic - they all succeed or all fail together.

**High Availability Built-In**: Depending on your chosen consensus model ([Event Sourcing](/rumi-core/guides/developing-applications/microservice-template/event-sourcing-template.md) or [State Replication](/rumi-core/guides/developing-applications/microservice-template/state-replication-template.md)), the AEP Engine automatically replicates data to backup instances and establishes consensus before committing transactions.

## What You'll Learn

This section covers the complete message processing lifecycle:

### [Handling Messages](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages.md)

Learn how to write message handlers - the methods where all your business logic executes. Topics include:

* Writing your first handler
* Accessing and updating the microservice store
* Handler signatures and annotations
* Common patterns for message processing
* Programming fundamentals and rules you must follow
* Advanced topics like zero-garbage programming and transaction control

### [Sending Messages](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/sending-messages.md)

Learn how to create and send outbound messages from your handlers. Topics include:

* Creating and sending messages
* Message keys and topic resolution
* Channel configuration
* Unsolicited sends (messages not triggered by inbound messages)
* Send stability tracking

## Message Processing Models

Rumi supports two consensus models that affect how message processing works:

**Event Sourcing** (recommended for most applications):

* Your microservice store consists of your own POJOs
* The AEP Engine replicates inbound messages to backup instances
* Backups replay messages to rebuild store state
* Provides the lowest latency and highest throughput
* Business logic must be deterministic

**State Replication**:

* Your microservice store uses ADM-generated classes
* The AEP Engine replicates store changes to backup instances
* Provides simpler programming model for certain use cases
* See [Rumi documentation](https://docs.neeveresearch.com) for enhanced State Replication support

For conceptual understanding of both models, see [Consensus Models](/rumi-core/concepts/consensus-models.md).

## Best Practices

**Keep Handlers Fast**: Handlers should complete quickly (typically microseconds to milliseconds). Avoid blocking operations, long computations, or external I/O.

**Design for Horizontal Scaling**: Partition your data across multiple microservice instances using message keys. Each instance processes a subset of messages based on their keys.

**Embrace Determinism**: Especially with Event Sourcing, ensure your business logic produces the same results given the same inputs. Don't rely on system time, random numbers, or external state.

**Use Transactions Wisely**: For most cases, rely on automatic transaction management. Use [transaction controls](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages/controlling-transactions.md) only when you have specific requirements like incremental commits for large batches.

## Getting Started

If you're new to Rumi message processing, we recommend reading in this order:

1. [Handling Messages - Programming Fundamentals](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages/programming-fundamentals.md) - Essential rules you must understand
2. [Handling Messages](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages.md) - How to write your first handler
3. [Sending Messages](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/sending-messages.md) - How to send outbound messages

## See Also

* [Consensus Models](/rumi-core/concepts/consensus-models.md) - Understand Event Sourcing vs State Replication
* [Cluster Consensus](/rumi-core/concepts/microservice-operation/cluster-consensus.md) - How consensus is established
* [Transactions](/rumi-core/concepts/transactions.md) - Transaction semantics and guarantees
* [Configuring Messaging](https://github.com/rumidata/nvx-rumi-docs/blob/claude-refactor/.gitbook/assets/README.md) - How to connect to message buses and subscribe to channels