### Run Database Example with Docker Compose

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/README.md

For database examples, start the required database using Docker Compose and then run the application.

```bash
# In the example directory
docker-compose up -d

# Then run the application
./gradlew bootRun
```

--------------------------------

### Run the SQL Server Example Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-sqlserver/README.md

Commands to run the Namastack Outbox example with SQL Server. This includes starting the database, waiting for initialization, and running the application.

```bash
./gradlew :namastack-outbox-example-sqlserver:bootRun
```

--------------------------------

### Running the Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-modulith/README.md

Commands to start the Docker Compose environment and run the Spring Boot application.

```bash
docker compose up -d
./gradlew bootRun
```

--------------------------------

### Run the Example Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-table-prefix-jdbc/README.md

Commands to execute the example application using Gradle.

```bash
./gradlew :namastack-outbox-example-table-prefix-jdbc:bootRun
```

```bash
cd namastack-outbox-examples/namastack-outbox-example-table-prefix-jdbc
./gradlew bootRun
```

--------------------------------

### Run Namastack Outbox Example (Gradle)

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-mongodb/README.md

Execute the Namastack Outbox custom collection prefix example using Gradle. This command starts the application with the specified configuration.

```bash
./gradlew :namastack-outbox-example-collection-prefix-mongodb:bootRun
```

--------------------------------

### Run the Example Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-tracing/README.md

Execute this Gradle command to build and run the Namastack Outbox tracing example application.

```bash
./gradlew :namastack-outbox-example-tracing:bootRun
```

--------------------------------

### Run the Annotation Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-annotation/README.md

Command to execute the annotation-based outbox example using Gradle.

```bash
./gradlew :namastack-outbox-example-annotation:bootRun
```

--------------------------------

### Run Namastack Outbox Example from Examples Directory (Gradle)

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-mongodb/README.md

Execute the Namastack Outbox custom collection prefix example by navigating to the examples directory and running the Gradle bootRun command.

```bash
cd namastack-outbox-examples/namastack-outbox-example-collection-prefix-mongodb
./gradlew bootRun
```

--------------------------------

### Run Multicaster Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-multicaster/README.md

Command to execute the multicaster example application using Gradle.

```bash
./gradlew :namastack-outbox-example-multicaster:bootRun
```

--------------------------------

### Example Project Structure

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/README.md

Overview of the typical file structure for each Namastack Outbox example project.

```text
namastack-outbox-example-*
├── README.md                    # Detailed example documentation
├── build.gradle.kts             # Gradle build configuration
├── docker-compose.yml           # Database setup (if applicable)
└── src/
    └── main/
        ├── kotlin/ (or java/)   # Application code
        │   └── io/namastack/demo/
        │       ├── DemoApplication.kt
        │       ├── *Handler.kt   # Outbox handlers
        │       └── customer/     # Domain model
        └── resources/
            └── application.yml   # Configuration
```

--------------------------------

### Start Local Development Server

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/README.md

Starts a local development server for live preview. Changes are reflected without restarting.

```bash
yarn start
```

--------------------------------

### Start MongoDB Instance with Docker

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-mongodb/README.md

Run a MongoDB instance locally using Docker. This is a prerequisite for the example.

```bash
docker run -d --name mongodb -p 27017:27017 mongo:8
```

--------------------------------

### Run Java Outbox Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-java/README.md

Executes the Java-based outbox example application using the Gradle wrapper.

```bash
./gradlew :namastack-outbox-example-java:bootRun
```

--------------------------------

### Run JDBC Example via Gradle

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-jdbc/README.md

Commands to execute the JDBC example application using the Gradle wrapper.

```bash
./gradlew :namastack-outbox-example-jdbc:bootRun
```

```bash
cd namastack-outbox-examples/namastack-outbox-example-jdbc
./gradlew bootRun
```

--------------------------------

### Run the Namastack Outbox Rabbit Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-rabbit/README.md

Execute this command to build and run the example application. It will register customers, schedule outbox records, send events to RabbitMQ, and remove customers.

```bash
./gradlew :namastack-outbox-example-rabbit:bootRun
```

--------------------------------

### Run Namastack Outbox H2 Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-h2/README.md

Executes the H2-based outbox example application using Gradle.

```bash
./gradlew :namastack-outbox-example-h2:bootRun
```

--------------------------------

### Run the PostgreSQL Example Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-postgresql/README.md

Execute this Gradle command to build and run the Namastack Outbox PostgreSQL example application. This command assumes you are in the project's root directory.

```bash
./gradlew :namastack-outbox-example-postgresql:bootRun
```

--------------------------------

### Run Fallback Handler Example Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-fallback/README.md

Execute this Gradle command to run the example application. The application will simulate failures, trigger retries, and invoke the fallback handler.

```bash
./gradlew :namastack-outbox-example-fallback:bootRun
```

--------------------------------

### Run JPA Table Prefix Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-table-prefix-jpa/README.md

Execute the Gradle task to run the Namastack Outbox JPA table prefix example with H2.

```bash
./gradlew :namastack-outbox-example-table-prefix-jpa:bootRun
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/README.md

Installs project dependencies using Yarn. Run this command before local development or building.

```bash
yarn
```

--------------------------------

### Run Flyway JDBC Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-flyway-jdbc/README.md

Execute this Gradle command to run the Flyway JDBC example. The application will apply migrations, register customers, schedule outbox events, and process them.

```bash
./gradlew :namastack-outbox-example-flyway-jdbc:bootRun
```

--------------------------------

### MongoDB Setup Script

Source: https://github.com/namastack/namastack-outbox/blob/main/README.md

A JavaScript script for setting up the MongoDB schema for Namastack Outbox.

```javascript
db.createCollection("outbox_event");
db.outbox_event.createIndex({ "created_at": 1, "processed_at": 1 });
db.outbox_event.createIndex({ "aggregate_type": 1, "aggregate_id": 1 });
```

--------------------------------

### Partition Distribution Scenarios

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/docs/reference/core.md

Examples of how partitions are distributed across instances during normal operation, failure, and scaling events.

```text
Instance 1: Partitions 0-84   (85 partitions)
Instance 2: Partitions 85-169 (85 partitions)
Instance 3: Partitions 170-255 (86 partitions)
```

```text
Instance 1: Partitions 0-84, 170-211   (127 partitions)
Instance 3: Partitions 85-169, 212-255 (129 partitions)
```

```text
Instance 1: Partitions 0-63    (64 partitions)
Instance 2: Partitions 64-127  (64 partitions)
Instance 3: Partitions 128-191 (64 partitions)
Instance 4: Partitions 192-255 (64 partitions)
```

--------------------------------

### Run the Namastack Outbox SNS Example Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-sns/README.md

Execute this command to build and run the Spring Boot application that demonstrates the outbox pattern with SNS.

```bash
./gradlew bootRun
```

--------------------------------

### Start Kafka with Docker Compose

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-kafka/README.md

Use this command to start Kafka and Kafka UI services using Docker Compose. Ensure Kafka is accessible on port 9092.

```bash
docker-compose up -d
```

--------------------------------

### Run MongoDB Setup Script (Default)

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/docs/reference/mongodb-schema.md

Execute the provided mongosh script to set up default MongoDB collections and indexes.

```bash
mongosh mongodb://localhost:27017/mydb schema/mongodb-setup.js
```

--------------------------------

### Clone Repository and Setup Remotes

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.6.x/contributing.md

Clone your fork of the repository and add the upstream remote to fetch changes from the main project.

```bash
git clone https://github.com/YOUR_USERNAME/namastack-outbox.git
cd namastack-outbox
git remote add upstream https://github.com/namastack/namastack-outbox.git
```

--------------------------------

### MongoDB Setup Dependencies

Source: https://github.com/namastack/namastack-outbox/blob/main/README.md

Add the MongoDB starter dependency to your Gradle project for MongoDB integration.

```gradle
dependencies {
    implementation(platform("io.namastack:namastack-outbox-bom:1.7.0"))
    implementation("io.namastack:namastack-outbox-starter-mongodb")
}
```

--------------------------------

### Trigger the Example Endpoint

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-tracing/README.md

Send an HTTP request to this endpoint to trigger the outbox pattern and observe the distributed tracing in action.

```bash
curl http://localhost:8080/
```

--------------------------------

### Flyway Migration File Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/docs/reference/database.md

Add a Flyway migration file to 'src/main/resources/db/migration/'. The content should be copied from the appropriate schema file for your database.

```sql
-- V1__create_outbox_tables.sql
-- Copy the content from the appropriate schema file for your database
```

--------------------------------

### JPA Setup Dependencies

Source: https://github.com/namastack/namastack-outbox/blob/main/README.md

Add the JPA starter dependency to your Gradle project for JPA/Hibernate integration.

```gradle
dependencies {
    implementation(platform("io.namastack:namastack-outbox-bom:1.7.0"))
    implementation("io.namastack:namastack-outbox-starter-jpa")
}
```

--------------------------------

### Example KDoc

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.5.x/contributing.md

An example of KDoc comments for a public API, explaining its purpose, parameters, and exceptions.

```kotlin
/**
 * Schedules a record for asynchronous processing via the outbox pattern.
 *
 * The record is persisted atomically with your business transaction and
 * processed by registered handlers after the transaction commits.
 *
 * @param payload The domain object to be processed
 * @param key Logical grouping key for ordered processing
 * @param additionalContext Optional context metadata (tracing, tenant info)
 * @throws IllegalStateException if called outside a transaction
 *
 * @since 1.0.0
 */
fun schedule(payload: Any, key: String, additionalContext: Map<String, String> = emptyMap())
```

--------------------------------

### Run the Namastack Outbox Kafka Example Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-kafka/README.md

Execute this Gradle command to run the application. It will register customers, schedule outbox records, send them to Kafka, and then remove the customers.

```bash
./gradlew :namastack-outbox-example-kafka:bootRun
```

--------------------------------

### Test Naming Convention Examples

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.5.x/contributing.md

Examples of descriptive test names following the convention for Kotlin tests.

```kotlin
@Test
fun `creates record for single handler`() { ... }
```

```kotlin
@Test
fun `retries failed record with exponential backoff`() { ... }
```

```kotlin
@Test
fun `does not process record before next retry time`() { ... }
```

--------------------------------

### Initial Partition Assignment (3 Instances)

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.5.x/reference/core.md

Illustrates the initial distribution of 256 partitions across three running instances.

```text
Instance 1: Partitions 0-84   (85 partitions)
Instance 2: Partitions 85-169 (85 partitions)
Instance 3: Partitions 170-255 (86 partitions)
```

--------------------------------

### Clone and Configure Repository

Source: https://github.com/namastack/namastack-outbox/blob/main/CONTRIBUTING.md

Initial steps to set up a local development environment by cloning the fork and adding the upstream remote.

```bash
git clone https://github.com/YOUR_USERNAME/namastack-outbox.git
cd namastack-outbox
```

```bash
git remote add upstream https://github.com/namastack/namastack-outbox.git
```

--------------------------------

### Run the Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-mariadb/README.md

Execute the application using the Gradle wrapper.

```bash
./gradlew :namastack-outbox-example-mariadb:bootRun
```

--------------------------------

### Outbox Gauge Metrics Examples

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/docs/reference/observability.md

Examples of how to use outbox metrics for monitoring operational state. These gauges provide counts and status of records and cluster health.

```text
outbox.records{outbox.record.status="new"}
```

```text
outbox.records{outbox.record.status="failed"}
```

```text
outbox.instance.records.pending
```

```text
outbox.cluster.instances.active
```

```text
outbox.cluster.partitions.unassigned
```

--------------------------------

### Run the Application

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-mysql/README.md

Execute the application using the Gradle wrapper.

```bash
./gradlew :namastack-outbox-example-mysql:bootRun
```

--------------------------------

### Example Test Names (Kotlin)

Source: https://github.com/namastack/namastack-outbox/blob/main/CONTRIBUTING.md

Examples of descriptive test names for Kotlin unit tests using the `@Test` annotation. These names clearly indicate the scenario being tested.

```kotlin
@Test
fun `creates record for single handler`() { ... }
```

```kotlin
@Test
fun `retries failed record with exponential backoff`() { ... }
```

```kotlin
@Test
fun `does not process record before next retry time`() { ... }
```

--------------------------------

### Start Grafana LGTM Stack

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-tracing/README.md

Run this command to start the Grafana LGTM stack, which includes Grafana, OpenTelemetry Collector, Loki, Tempo, and Mimir for trace visualization.

```bash
docker compose up -d
```

--------------------------------

### Get Partition for Aggregate Key

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.5.x/reference/core.md

This Kotlin code snippet demonstrates how to get the partition for a given aggregate key using the PartitionHasher. This is part of the hash-based partitioning mechanism for horizontal scaling.

```kotlin
val partition = PartitionHasher.getPartitionForAggregate("order-123")
```

--------------------------------

### Java Outbox Fallback Handler Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.6.x/reference/handlers.md

Illustrates the implementation of a fallback handler in Java, similar to the Kotlin example, where a single fallback handles failures for multiple primary handlers processing the same OrderEvent payload.

```java
import org.springframework.stereotype.Component;

@Component
public class OrderHandlers {
    // Both handlers share the same fallback
    @OutboxHandler
    public void handleOrderCreated(OrderEvent payload) {
        orderService.create(payload);
    }
    @OutboxHandler
    public void handleOrderUpdated(OrderEvent payload) {
        orderService.update(payload);
    }
    @OutboxFallbackHandler
    public void handleOrderFailure(OrderEvent payload, OutboxFailureContext context) {
        // Handles failures from both handleOrderCreated and handleOrderUpdated
        deadLetterQueue.publish(payload);
    }
}
```

--------------------------------

### Build and Test Project with Gradle

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.6.x/contributing.md

Commands to build all modules, run tests, generate coverage reports, and check/fix code style using Gradle.

```bash
# Build all modules
./gradlew build

# Run tests
./gradlew test

# Run tests with coverage
./gradlew test jacocoTestReport

# Check code style
./gradlew ktlintCheck

# Fix code style issues
./gradlew ktlintFormat

# Publish to local Maven repository (for testing)
./gradlew publishToMavenLocal
```

--------------------------------

### Community and Support

Source: https://github.com/namastack/namastack-outbox/blob/main/CONTRIBUTING.md

Information on how to get help and engage with the community.

```APIDOC
## Questions?

- For questions, open a [GitHub Discussion](https://github.com/namastack/namastack-outbox/discussions).
- Please check existing issues and discussions first.
- Join the community and help others!
```

--------------------------------

### Partition Distribution with New Instance Joining

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.1.x/reference/core.md

Demonstrates partition redistribution when a new instance joins the cluster. Partitions are rebalanced evenly across all active instances.

```text
Instance 1: Partitions 0-63    (64 partitions)
Instance 2: Partitions 64-127  (64 partitions)
Instance 3: Partitions 128-191 (64 partitions)
Instance 4: Partitions 192-255 (64 partitions)
```

--------------------------------

### Run Flyway JPA Example

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-examples/namastack-outbox-example-flyway-jpa/README.md

Execute the Gradle task to run the application. This will apply Flyway migrations, register customers, schedule outbox records, and process them asynchronously.

```bash
./gradlew :namastack-outbox-example-flyway-jpa:bootRun
```

--------------------------------

### Annotation-based Handlers (Java)

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.0.x/reference/handlers.md

Example of using the `@OutboxHandler` annotation in Java for method-level handler registration.

```APIDOC
## Annotation-based Handlers (Java)

### Description
Use the `@OutboxHandler` annotation on methods to register handlers without implementing interfaces. This is useful for classes handling multiple record types or mixing handler logic with other operations.

### Method
Annotated methods: `handleOrderCreated(OrderCreatedRecord payload)`, `handlePaymentProcessed(PaymentProcessedRecord payload)`, `handleAny(Object payload, OutboxRecordMetadata metadata)`

### Endpoint
N/A (Annotation-based)

### Request Body
- **payload** (T or Object) - Required - The outbox record payload.
- **metadata** (OutboxRecordMetadata) - Required for generic handlers - Metadata associated with the outbox record.

### Response
N/A (Method Execution)

### Request Example
```java
@Component
public class MyHandlers {
    @OutboxHandler
    public void handleOrderCreated(OrderCreatedRecord payload) {
        // ...
    }

    @OutboxHandler
    public void handlePaymentProcessed(PaymentProcessedRecord payload) {
        // ...
    }
    
    @OutboxHandler
    public void handleAny(Object payload, OutboxRecordMetadata metadata) {
        // Generic handler via annotation
    }
}
```
```

--------------------------------

### Annotation-based Handlers (Kotlin)

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.0.x/reference/handlers.md

Example of using the `@OutboxHandler` annotation in Kotlin for method-level handler registration.

```APIDOC
## Annotation-based Handlers (Kotlin)

### Description
Use the `@OutboxHandler` annotation on methods to register handlers without implementing interfaces. This is useful for classes handling multiple record types or mixing handler logic with other operations.

### Method
Annotated methods: `handleOrderCreated(payload: OrderCreatedRecord)`, `handlePaymentProcessed(payload: PaymentProcessedRecord)`, `handleAny(payload: Any, metadata: OutboxRecordMetadata)`

### Endpoint
N/A (Annotation-based)

### Request Body
- **payload** (T or Any) - Required - The outbox record payload.
- **metadata** (OutboxRecordMetadata) - Required for generic handlers - Metadata associated with the outbox record.

### Response
N/A (Method Execution)

### Request Example
```kotlin
@Component
class MyHandlers {
    @OutboxHandler
    fun handleOrderCreated(payload: OrderCreatedRecord) {
        // ...
    }

    @OutboxHandler
    fun handlePaymentProcessed(payload: PaymentProcessedRecord) {
        // ...
    }
    
    @OutboxHandler
    fun handleAny(payload: Any, metadata: OutboxRecordMetadata) {
        // Generic handler via annotation
    }
}
```
```

--------------------------------

### Typed Handlers (Java)

Source: https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-docs/versioned_docs/version-1.0.x/reference/handlers.md

Example of a type-safe handler in Java for processing specific outbox records.

```APIDOC
## Typed Handlers (Java)

### Description
Implement the `OutboxTypedHandler` interface to create type-safe handlers for specific record types.

### Method
`handle(payload: T)` or `handle(payload: T, metadata: OutboxRecordMetadata)`

### Endpoint
N/A (Interface Implementation)

### Request Body
- **payload** (T) - Required - The specific outbox record payload.
- **metadata** (OutboxRecordMetadata) - Optional - Metadata associated with the outbox record.

### Response
N/A (Method Execution)

### Request Example
```java
@Component
public class OrderCreatedHandler implements OutboxTypedHandler<OrderCreatedRecord> {
    @Override
    public void handle(OrderCreatedRecord payload) {
        System.out.println("Processing order: " + payload.getOrderId());
        eventPublisher.publish(payload);
    }
}
```
```