Features

• Event Contract
• Outbox Pattern
• Transactional Outbox Pattern
• Idempotency Pattern
• Spring Boot Auto Configuration
• DynamoDB Integration
• SNS Integration
• SQS Integration
• TraceId Propagation
• Standardized Logging
• GitHub Packages Distribution

---

Production Usage

This library is currently used by the following microservices:

• Order Service
• Payment Service
• Inventory Service
• Notification Service

The library provides a shared implementation of event contracts, Outbox, Idempotency and Spring Boot auto-configuration across all services.

---

Architecture

Outbox Pattern

Idempotency Pattern

---

Event Contract

All events implement a common contract:

public interface Event {

    UUID eventId();

    String traceId();

    String eventType();
}

Example:

public record PaymentApprovedEvent(
        UUID eventId,
        String traceId,
        String eventType,
        String orderId)
        implements Event {
}

---

Installation

Configure GitHub Packages

Add the GitHub Packages repository:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/fredfmelo/event-driven-core</url>
    </repository>
</repositories>

Configure Maven credentials in ~/.m2/settings.xml:

<settings>
    <servers>
        <server>
            <id>github</id>
            <username>YOUR_GITHUB_USERNAME</username>
            <password>YOUR_GITHUB_TOKEN</password>
        </server>
    </servers>
</settings>

Consumers must configure a GitHub Personal Access Token with the read:packages permission in ~/.m2/settings.xml.

Generate a GitHub Personal Access Token with:

• read:packages

Add the Dependency

<dependency>
    <groupId>com.fredfmelo</groupId>
    <artifactId>event-driven-core</artifactId>
    <version>1.0.0</version>
</dependency>

---

Configuration

The library requires an implementation of DynamoProperties to provide the DynamoDB table name used by the Outbox and Idempotency components.

Step 1 - Implement DynamoProperties

package com.fredfmelo.orderservice.config;

import org.springframework.stereotype.Component;

import com.fredfmelo.eventdrivencore.config.DynamoProperties;

import lombok.RequiredArgsConstructor;

@Component
@RequiredArgsConstructor
public class ServiceDynamoProperties implements DynamoProperties {

    private final ServiceConfig serviceConfig;

    @Override
    public String tableName() {
        return serviceConfig.getDynamodb().getTableName();
    }
}

Step 2 - Configure the table name

aws:
  dynamodb:
    table-name: ORDER

The configured table is used by:

• Outbox Repository
• Idempotency Repository

---

Auto Configuration

The library provides Spring Boot auto-configuration.

Idempotency Module

Automatically enabled when the application provides:

DynamoProperties

Provides:

• IdempotentExecutor
• IdempotencyRepository

Outbox Module

Automatically enabled when the application provides:

DynamoProperties
OutboxEventPublisher

Provides:

• OutboxService
• OutboxRepository
• OutboxProcessor

This allows services to consume only the modules they need.

---

Using the Outbox Pattern

Create and persist the Outbox entry together with the business transaction.

OrderCreatedEvent event = new OrderCreatedEvent(
        UUID.randomUUID(),
        traceId,
        "ORDER_CREATED",
        ...
);

OutboxEntity outboxEntity =
        outboxService.create(event);

transactionRepository.saveOrderAndOutbox(
        order,
        outboxEntity);

The Outbox Processor will automatically:

• Read pending events
• Publish events to SNS
• Mark events as processed

---

Using the Idempotency Pattern

Wrap message processing with the IdempotentExecutor.

idempotentExecutor.execute(
        event,
        () -> paymentService.process(event)
);

The executor will:

• Detect duplicate events
• Prevent duplicate processing
• Persist processing status
• Log processing metrics

---

Logging

The library promotes standardized logs across all services.

Example:

Event received: traceId=abc123, eventId=123, eventType=PAYMENT_APPROVED

Event processed: traceId=abc123, eventId=123, eventType=PAYMENT_APPROVED, durationMs=42

Publishing event: traceId=abc123, eventId=123, eventType=PAYMENT_APPROVED

Event published: traceId=abc123, eventId=123, eventType=PAYMENT_APPROVED, durationMs=15

---

Supported Technologies

• Java 21+
• Spring Boot 3.5+
• DynamoDB
• SNS
• SQS

---

Roadmap

Current

• Event Contract
• Outbox Pattern
• Transactional Outbox
• Idempotency Pattern
• Spring Boot Auto Configuration
• DynamoDB Integration
• SNS Integration
• SQS Integration
• TraceId Propagation
• Standardized Logging
• GitHub Packages Distribution

Planned

• Micrometer Metrics Integration
• Grafana / Loki Observability
• OpenTelemetry Distributed Tracing
• Dead Letter Queue (DLQ) Utilities
• Retry Utilities
• Event Versioning Support
• Event Schema Validation
• Integration Test Utilities
• Maven Central Publishing

---

Design Goals

• Reliability
• Simplicity
• Reusability
• Observability
• Maintainability
• Developer Experience
• Low Service Coupling
• Production Readiness

---

License

MIT