DEV Community: Allan Roberto

How I Added LangChain4j Without Letting It Take Over My Spring Boot App

Allan Roberto — Mon, 06 Apr 2026 14:16:05 +0000

Most AI examples look clean for about five minutes.

Then the framework starts leaking everywhere:

controllers know about embedding models
services return framework types
retrieval becomes a black box
swapping providers means rewriting half the application

I did not want that here.

This project is a Spring Boot knowledge base backed by PostgreSQL, pgvector, and LangChain4j. It supports a practical RAG-style flow:

accept documents through an HTTP API
split them into chunks
generate embeddings
store vectors in PostgreSQL
retrieve relevant chunks with hybrid search
build a prompt and generate an answer

The interesting part is not that LangChain4j is present. The interesting part is how it is present.

LangChain4j is now part of the real execution flow, but it is still treated as an outbound technology. The application core owns the use cases. PostgreSQL still owns retrieval. LangChain4j helps with chunking, embeddings, prompt templating, and chat, but it does not define the architecture.

The architectural rule

The project is organized by business context first:

document: ingestion, indexing, chunk persistence, indexing events
search: retrieval, prompt construction, answer generation
shared: AI ports, LangChain4j adapters, and configuration

Inside each context, the code follows a hexagonal structure:

domain
application
adapter/in
adapter/out

That gives the project a simple rule: dependencies point inward.

controllers call application services
application services depend on ports
adapters implement those ports
domain classes stay free of framework concerns

This matters because the project touches several infrastructure-heavy concerns at once:

HTTP
Spring events
PostgreSQL and pgvector
LangChain4j

If you let all of those bleed into the core, the use cases disappear. The application becomes a pile of framework-shaped services.

What LangChain4j does here, and what it does not do

The code defines its own application ports:

DocumentChunker
EmbeddingPort
ChatPort

That one decision keeps the boundaries clean.

The application does not talk directly to:

DocumentSplitter
EmbeddingModel
ChatModel

Instead, LangChain4j is pushed to the edge through adapters. That means the use cases depend on the application contracts they need, not on the framework types that happen to implement them today.

This is the difference between ?using a framework? and ?letting a framework shape your codebase.?

The indexing flow stays in the application core

The document creation endpoint stays thin. It accepts a request and delegates to the application service. It does not know about chunks, embeddings, or vector storage.

That service persists the document and publishes an application-level event. Then an event listener forwards the event into the indexing use case:

@Transactional
@EventListener
public void handle(KnowledgeDocumentCreatedEvent event) {
    indexer.index(event.documentId());
}

That listener is intentionally boring. It is transport glue, not business logic.

The real work lives in KnowledgeDocumentIndexer:

List<String> chunks = documentChunker.chunk(document.getContent());

int index = 0;
for (String chunkText : chunks) {
    EmbeddingVector embedding = embeddingPort.embed(chunkText);

    KnowledgeDocumentChunk knowledgeChunk = KnowledgeDocumentChunk.builder()
            .documentId(document.getId())
            .chunkIndex(index++)
            .chunkText(chunkText)
            .embedding(embedding.values())
            .embeddingModel(embedding.modelName())
            .build();

    chunkStore.save(knowledgeChunk);
}

This is exactly where chunking and embedding belong: in the indexing use case.

Not in the controller. Not in the event listener. Not hidden in a framework callback.

LangChain4j is useful here because it is constrained

One of the better examples is chunking.

The project does not expose LangChain4j DocumentSplitter directly to the core. Instead, the application depends on DocumentChunker, and the adapter implementation is ParagraphPreservingDocumentSplitter.

That class keeps the original project behavior of one paragraph per chunk, but still uses LangChain4j internally when a paragraph is too large:

@Override
public List<String> chunk(String text) {
    return split(Document.from(text)).stream()
            .map(TextSegment::text)
            .toList();
}

And the actual paragraph handling is explicit:

String[] paragraphs = document.text().split("\\R\\s*\\R");

for (String paragraph : paragraphs) {
    String normalized = paragraph.strip();

    if (normalized.isEmpty()) {
        continue;
    }

    List<TextSegment> paragraphSegments =
            characterSplitter.split(Document.from(normalized));
}

That is a good pattern for framework integration:

preserve the business behavior you care about
use the framework for the mechanics it is good at
do not accept framework defaults blindly

The same idea shows up in the embedding adapter:

@Override
public EmbeddingVector embed(String text) {
    return new EmbeddingVector(
            embeddingModel.embed(text).content().vector(),
            embeddingModel.modelName()
    );
}

The use case gets exactly what it needs:

vector values
model name

It does not need LangChain4j response wrappers in the application layer.

The chat side follows the same pattern:

@Override
public String ask(String prompt) {
    return chatModel.chat(prompt);
}

The application wants an answer for a prompt. That is the contract. It should not need to know about ChatModel.

Retrieval still belongs to PostgreSQL

This is the part I like most in the project.

LangChain4j was introduced without giving retrieval away to a framework abstraction.

The retrieval flow in RetrievalService is still explicit:

float[] questionEmbedding = embeddingPort.embed(question).values();

String vector = vectorFormatter.toPgVector(questionEmbedding);
String metadataFilterJson = toMetadataFilterJson(metadataFilters);

List<SimilarChunk> results =
        knowledgeChunkSearchPort.searchTopK(
                vector,
                normalizeKeywordQuery(keywordQuery),
                metadataFilterJson,
                topK
        );

The actual search strategy still lives in PostgreSQL:

vector similarity through pgvector
keyword ranking through full-text search
exact metadata filtering through jsonb

That is an important architectural choice.

Too many examples treat retrieval like a magical AI feature. It is not. It is a search problem. In this project, PostgreSQL remains visible as the system that ranks and filters the data. That keeps the behavior understandable and debuggable.

Prompt rendering is framework-assisted, not framework-owned

Prompt construction uses LangChain4j PromptTemplate:

private static final PromptTemplate PROMPT_TEMPLATE = PromptTemplate.from("""
        You are an assistant for a knowledge base.
        Answer only using the context below.
        If the answer is not present in the context, say you do not know.

        Context:
        {{context}}

        User question:
        {{question}}

        Answer:
        """);

But PromptBuilder still returns a plain String to the application layer.

That is the right compromise. LangChain4j helps with the mechanics of prompt templating, but the framework does not become the API of the core service.

The fake models are not a shortcut anymore

The project still ships with fake models, and that is a good thing.

The important detail is that they are fake LangChain4j models now:

FakeEmbeddingModel implements LangChain4j EmbeddingModel
FakeChatModel implements LangChain4j ChatModel

That means local development and tests can run without provider credentials, while still exercising the same architectural flow a real provider would use.

This is much better than maintaining a fake architecture for local work and a separate real architecture for production. Here, replacing the fake provider is mostly a wiring change.

One constraint that should stay explicit

There is one technical detail that should never be buried in the fine print:

the database column is vector(1536)
the current fake embedding model also returns 1536 dimensions

If you swap in a real embedding provider, that dimension has to match or the schema has to change.

That is not an implementation detail. It is part of the persistence contract.

Why this design works

What makes this project credible is not that it uses LangChain4j.

It is that the project uses LangChain4j without surrendering the architecture.

The core ideas are simple:

define use cases first
keep framework dependencies behind ports
let PostgreSQL stay responsible for retrieval
keep controllers and listeners thin
make provider replacement a wiring problem instead of a rewrite

That is the part worth copying.

If you are building AI features into a Spring Boot application, the lesson is not ?avoid frameworks.? The lesson is narrower and more useful:

Use frameworks as adapters.
Do not let them become your architecture.

Meaning: How Data Vectorization Powers AI
Turning PostgreSQL Into a Vector Database with Docker
Indexing Knowledge Base Content with Spring Boot and pgvector
Building Semantic Search with Spring Boot, PostgreSQL, and pgvector (RAG Retrieval)
How I Added LangChain4j Without Letting It Take Over My Spring Boot App

Project Here

From Outbox to Email Delivery: Extending the Kafka Flow in Spring Boot

Allan Roberto — Wed, 25 Mar 2026 13:42:29 +0000

In the previous article, I showed how to create an order, save an outbox event in the same transaction, and publish that event to Kafka using the outbox pattern.

This new step is the natural sequence of that flow.

Now the application does more than publish OrderCreatedEvent. It also consumes that event, prepares an invoice email, stores the email content, creates a new outbox event for email delivery, and dispatches the email asynchronously.

The full project is here: sb-kafka-producer-sample

Why not send the email directly in the consumer?

Because that makes the consumer responsible for too much:

reading from Kafka
loading data from the database
building the email
talking to SMTP
updating order state

That is where partial failure becomes painful.

For example:

the email is sent successfully
the order status update fails right after

Now the user received the invoice, but your system still says it was not delivered.

So instead of sending the email directly inside the consumer, I split the process into two steps:

The consumer prepares durable state.
The outbox dispatcher performs the side effect.

Step 1: consume the Kafka event and generate the email request

The Kafka consumer is intentionally small:

@ConditionalOnProperty(value = "app.kafka.invoice-consumer-enabled", havingValue = "true", matchIfMissing = true)
@Component
public class OrderCreatedInvoiceConsumer {

  private final ObjectMapper objectMapper;
  private final CreateInvoiceEmailFromOrderCreatedEventService service;

  public OrderCreatedInvoiceConsumer(
      ObjectMapper objectMapper,
      CreateInvoiceEmailFromOrderCreatedEventService service
  ) {
    this.objectMapper = objectMapper;
    this.service = service;
  }

  @KafkaListener(
      topics = "${app.kafka.order-topic}",
      groupId = "${app.kafka.invoice-consumer-group-id}",
      autoStartup = "${app.kafka.invoice-consumer-enabled:true}"
  )
  public void consume(String payload) {
    service.create(deserialize(payload));
  }

  private OrderCreatedEvent deserialize(String payload) {
    try {
      return objectMapper.readValue(payload, OrderCreatedEvent.class);
    } catch (JacksonException exception) {
      throw new IllegalStateException("Could not deserialize consumed order event", exception);
    }
  }
}

This class only does adapter work:

listens to Kafka
deserializes the payload
delegates to the use case

That keeps the consumer easy to understand and easy to test.

Step 2: store the invoice email and create a new outbox event

Once the order event is consumed, the application service:

loads the user by userId
builds the invoice body
saves the email content
saves a new outbox event that references that email

@Transactional
public void create(OrderCreatedEvent event) {
  User user = loadOrderUserService.loadById(event.userId());

  InvoiceEmail invoiceEmail = invoiceEmailPort.save(new InvoiceEmail(
      UUID.randomUUID(),
      user.id(),
      event.orderId(),
      user.email(),
      "Invoice for order #" + event.orderId(),
      invoiceEmailBodyFactory.create(user, event),
      OffsetDateTime.now(),
      null
  ));

  outboxEventPort.save(new OutboxEvent(
      UUID.randomUUID(),
      OutboxAggregateType.INVOICE_EMAIL,
      invoiceEmail.id().toString(),
      OutboxEventType.EMAIL_INVOICE_REQUESTED,
      createPayload(new InvoiceEmailOutboxPayload(invoiceEmail.id())),
      OutboxStatus.PENDING,
      OffsetDateTime.now(),
      null,
      null
  ));
}

This was the key design choice for me.

Instead of putting the full email in the outbox payload, I store the rendered email in the database and keep only a reference in the outbox event.

That gives a few benefits:

the email content is auditable
retries do not need to rebuild the message
multiple emails per order are supported
the outbox payload stays small

Building an invoice-like email

The email body is generated separately, not inside the listener.

That was important because the email has business content:

user name
item list
quantities
total amount

In other words, this is not just a notification email. It behaves more like a simple invoice.

Keeping that rendering logic in its own component made the implementation cleaner and the tests more focused.

Step 3: dispatch the email from the outbox

The second half of the flow happens in the outbox publisher.

It reads pending outbox events and routes each one to the correct dispatcher:

@Scheduled(fixedDelayString = "${app.outbox.fixed-delay-ms}")
public void publishPendingEvents() {
  for (OutboxEvent event : outboxEventPort.findProcessableEvents(batchSize, maxAttempts)) {
    try {
      resolveDispatcher(event.eventType()).dispatch(event);
      outboxEventPort.markPublished(event.id());
    } catch (Exception exception) {
      LOGGER.warn("Failed to publish outbox event {}", event.id(), exception);
      outboxEventPort.markFailed(event.id(), truncate(exception.getMessage()));
    }
  }
}

This is where the outbox became more useful than just "publish to Kafka".

Now it can also dispatch email-related events. The pattern became generic.

Step 4: send the email and update the order

The email dispatcher is responsible for the final side effect:

@Transactional
@Override
public void dispatch(OutboxEvent event) {
  InvoiceEmailOutboxPayload payload = deserialize(event.payload());

  InvoiceEmail invoiceEmail = invoiceEmailPort.findById(payload.invoiceEmailId())
      .orElseThrow(() -> new NotFoundException(
          "Invoice email not found for id " + payload.invoiceEmailId()
      ));

  emailSenderPort.send(invoiceEmail);
  invoiceEmailPort.markSent(invoiceEmail.id());
  orderPersistencePort.updateStatus(invoiceEmail.orderId(), OrderStatus.INVOICE_DELIVERED);
}

That sequence matters.

The order is updated to INVOICE_DELIVERED only after the email is actually sent.

This avoids saying the invoice was delivered when SMTP failed.

Retry support

Email delivery is a good candidate for retry.

SMTP failures are often temporary, so I added retry control in the outbox through attempt_count plus a configurable max-attempts.

That gives the system a safer behavior:

retry transient failures
stop retrying forever when the event is clearly broken

Without that, the email dispatcher would either fail too early or retry endlessly.

Why I like this version better

The biggest improvement is not the email itself. It is the separation of responsibilities.

Now the flow is:

Kafka consumer receives the event
application service prepares durable email state
outbox stores the delivery request
dispatcher sends the email
order status changes only after success

That is a much safer model than sending email directly from the listener.

It also keeps the code more aligned with hexagonal architecture:

adapters receive and send data
use cases coordinate business rules
side effects are isolated behind ports

Final thoughts

The first article was about producing events reliably.

This second step is about consuming them without turning the consumer into a fragile orchestration class.

For me, the main lesson is simple:

when a flow touches Kafka, database state, and an external service like SMTP, it is worth splitting preparation from delivery.

That small design decision makes failures easier to handle and the behavior much more predictable.

If you want to see the full implementation, here is the repository again: sb-kafka-producer-sample

[Boost]

Allan Roberto — Tue, 24 Mar 2026 13:56:28 +0000

Allan Roberto

Mar 24

Outbox Pattern with Kafka and Hexagonal Architecture in Spring Boot

#java #springboot #kafka #test

Comments

7 min read

Outbox Pattern with Kafka and Hexagonal Architecture in Spring Boot

Allan Roberto — Tue, 24 Mar 2026 13:56:07 +0000

When building microservices, one of the most common consistency problems is this:

what happens if the database transaction succeeds, but the Kafka publish fails?

If your service saves business data first and publishes the event afterward, you can end up with an order stored in the database and no event in Kafka. That is exactly the kind of distributed inconsistency the Outbox Pattern is designed to avoid.

In this article, I’ll use the repository below as the study case:

sb-kafka-producer-sample

This project is not just a simple Kafka producer. Its README explicitly states that it uses PostgreSQL, Kafka, Flyway, and the outbox pattern in a hexagonal architecture. It also exposes an asynchronous POST /api/orders endpoint that stores the order and the outbox event in the same transaction, and then a scheduled publisher sends pending events to Kafka.

Why the Outbox Pattern matters

The classic anti-pattern looks like this:

[ REST API ]
    ↓
[ Save order in DB ]
    ↓
[ Publish event to Kafka ]

This looks simple, but it is unsafe. If the database commit succeeds and Kafka fails right after, your system state becomes inconsistent.

The outbox pattern changes the flow to this:

[ REST API ]
    ↓
[ Save order ]
    ↓
[ Save outbox event ]  <-- same transaction
    ↓
[ Scheduled publisher reads pending outbox events ]
    ↓
[ Publish to Kafka ]
    ↓
[ Mark event as PUBLISHED or FAILED ]

That is exactly the strategy implemented by the repository. The order is persisted and the outbox event is saved together inside CreateOrderService, while OutboxPublisher later processes pending events.

Hexagonal Architecture in the repository

The repository README describes the project in hexagonal layers:

domain: business models and enums
application: ports, use cases, commands, and exceptions
adapter.in.web: REST controllers and validation
adapter.out.persistence: JPA entities, repositories, and persistence adapters
adapter.out.messaging: Kafka publishing and outbox polling
config: infrastructure configuration

That separation is important, because Kafka is not leaking into the use case layer. Instead, the application layer talks through ports, and the adapters implement them.

A simplified view looks like this:

domain/
application/
  port/
    in/
    out/
  usecase/
adapter/
  in/web/
  out/persistence/
  out/messaging/
config/

The core of the pattern: `CreateOrderService`

The most important class in this study case is CreateOrderService.

It:

validates duplicated products,
loads the user,
loads the products,
calculates totals,
saves the order through OrderPersistencePort,
creates an OutboxEvent with status PENDING,
stores the event through OutboxEventPort.

This is the most important part of the implementation:

@Async("taskExecutor")
@Transactional
@Override
public CompletableFuture<?> create(CreateOrderCommand command) {
    validateDuplicatedProducts(command.items());

    User user = loadOrderUserService.loadById(command.userId());
    Map<Long, Product> productMap = loadOrderProductsService.loadProductsByItems(command.items());

    List<OrderItem> items = command.items().stream()
        .map(item -> toOrderItem(item, productMap.get(item.productId())))
        .toList();

    BigDecimal totalAmount = items.stream()
        .map(OrderItem::lineTotal)
        .reduce(BigDecimal.ZERO, BigDecimal::add);

    Order savedOrder = orderPersistencePort.save(new Order(
        null,
        user.id(),
        user.name(),
        OrderStatus.CREATED,
        totalAmount,
        OffsetDateTime.now(),
        items
    ));

    outboxEventPort.save(new OutboxEvent(
        UUID.randomUUID(),
        "ORDER",
        savedOrder.id().toString(),
        "ORDER_CREATED",
        createPayload(toOrderCreatedEvent(savedOrder)),
        OutboxStatus.PENDING,
        OffsetDateTime.now(),
        null,
        null
    ));

    return CompletableFuture.completedFuture(savedOrder);
}

This is the key design choice: the use case does not publish directly to Kafka. It only persists the business state and the event description atomically.

The Outbox model

The repository models the outbox entry as a domain record:

public record OutboxEvent(
    UUID id,
    String aggregateType,
    String aggregateId,
    String eventType,
    String payload,
    OutboxStatus status,
    OffsetDateTime createdAt,
    OffsetDateTime processedAt,
    String errorMessage
) { }

This is a solid design because it includes:

an event identifier,
aggregate metadata,
serialized payload,
lifecycle status,
processing timestamp,
failure message.

The application port for this workflow is also explicit:

public interface OutboxEventPort {
    OutboxEvent save(OutboxEvent event);
    List<OutboxEvent> findAll();
    List<OutboxEvent> findProcessableEvents(int limit);
    void markPublished(UUID eventId);
    void markFailed(UUID eventId, String errorMessage);
}

That keeps the application independent from JPA and database details.

The publisher side

The scheduled publisher is implemented in OutboxPublisher.

It fetches processable events in batches, publishes them through OrderEventPublisherPort, and updates the outbox status accordingly:

@Scheduled(fixedDelayString = "${app.outbox.fixed-delay-ms}")
public void publishPendingEvents() {
    for (OutboxEvent event : outboxEventPort.findProcessableEvents(batchSize)) {
        try {
            orderEventPublisherPort.publish(event);
            outboxEventPort.markPublished(event.id());
        } catch (Exception exception) {
            LOGGER.warn("Failed to publish outbox event {}", event.id(), exception);
            outboxEventPort.markFailed(event.id(), truncate(exception.getMessage()));
        }
    }
}

That means the failure handling is also persisted, which is useful for observability and retries.

Kafka adapter

The concrete Kafka adapter is KafkaOrderEventPublisher, which implements OrderEventPublisherPort.

It deserializes the outbox payload into a typed OrderCreatedEvent and sends it with:

topic from configuration,
key = aggregateId,
value = typed event.

@Component
public class KafkaOrderEventPublisher implements OrderEventPublisherPort {

    private final KafkaTemplate<String, OrderCreatedEvent> kafkaTemplate;
    private final ObjectMapper objectMapper;
    private final String topic;

    @Override
    public void publish(OutboxEvent event) {
        kafkaTemplate.send(topic, event.aggregateId(), deserialize(event.payload())).join();
    }

    private OrderCreatedEvent deserialize(String payload) {
        try {
            return objectMapper.readValue(payload, OrderCreatedEvent.class);
        } catch (JacksonException exception) {
            throw new IllegalStateException("Could not deserialize order outbox payload", exception);
        }
    }
}

Using aggregateId as the Kafka key is a good choice because it helps preserve ordering for messages of the same aggregate.

Why this implementation is good

What I like in this repository is that it avoids the common mistake of mixing transport concerns into the use case.

The responsibilities are clean:

CreateOrderService handles business orchestration and stores the outbox event.
OutboxPublisher handles scheduling and delivery lifecycle.
KafkaOrderEventPublisher handles Kafka-specific concerns.
OutboxEventPort and OrderEventPublisherPort keep the application layer isolated from infrastructure.

That is exactly how the outbox pattern should look in a hexagonal architecture.

Tests in the repository

One thing I appreciated is that the repository already includes the right kinds of tests.

1. Use case test

CreateOrderServiceTest verifies that:

the order is created,
total amount is calculated,
the outbox event is saved,
the payload contains a serialized OrderCreatedEvent,
duplicated products are rejected.

Example:

@Test
void shouldCreateOrderAndOutboxEvent() {
    CreateOrderCommand command = new CreateOrderCommand(
        1L,
        List.of(
            new CreateOrderItemCommand(10L, 2),
            new CreateOrderItemCommand(20L, 1)
        )
    );

    when(loadOrderUserService.loadById(1L))
        .thenReturn(new User(1L, "User", "user@example.com"));

    when(loadOrderProductsService.loadProductsByItems(command.items()))
        .thenReturn(Map.of(
            10L, new Product(10L, "Notebook", new BigDecimal("12.50")),
            20L, new Product(20L, "Keyboard", new BigDecimal("45.90"))
        ));

    when(orderPersistencePort.save(any(Order.class)))
        .thenAnswer(invocation -> {
            Order order = invocation.getArgument(0, Order.class);
            return new Order(
                99L,
                order.userId(),
                order.userName(),
                OrderStatus.CREATED,
                order.totalAmount(),
                order.createdAt(),
                order.items()
            );
        });

    Order order = createOrderService.create(command).join();

    assertThat(order.id()).isEqualTo(99L);
    assertThat(order.totalAmount()).isEqualByComparingTo("70.90");

    ArgumentCaptor<OutboxEvent> captor = ArgumentCaptor.forClass(OutboxEvent.class);
    verify(outboxEventPort).save(captor.capture());

    OrderCreatedEvent event =
        new ObjectMapper().readValue(captor.getValue().payload(), OrderCreatedEvent.class);

    assertThat(event.orderId()).isEqualTo(99L);
    assertThat(event.totalAmount()).isEqualByComparingTo("70.90");
}

This is a strong unit test because it verifies not only that the port was called, but also that the serialized event payload is correct.

2. Kafka publisher unit test

KafkaOrderEventPublisherTest checks that the adapter:

deserializes the outbox payload,
publishes a typed OrderCreatedEvent,
uses the right topic and key.

@Test
void shouldDeserializeOutboxPayloadAndPublishTypedEvent() throws Exception {
    KafkaTemplate<String, OrderCreatedEvent> kafkaTemplate = mock(KafkaTemplate.class);
    ObjectMapper objectMapper = new ObjectMapper();

    KafkaOrderEventPublisher publisher =
        new KafkaOrderEventPublisher(kafkaTemplate, objectMapper, "orders.created");

    OrderCreatedEvent payload = new OrderCreatedEvent(
        99L,
        1L,
        "User",
        OrderStatus.CREATED,
        new BigDecimal("70.90"),
        OffsetDateTime.parse("2026-03-24T10:15:30Z"),
        List.of(new OrderCreatedItemEvent(
            10L, "Notebook", 2,
            new BigDecimal("12.50"),
            new BigDecimal("25.00")
        ))
    );

    OutboxEvent outboxEvent = new OutboxEvent(
        UUID.randomUUID(),
        "ORDER",
        "99",
        "ORDER_CREATED",
        objectMapper.writeValueAsString(payload),
        OutboxStatus.PENDING,
        OffsetDateTime.now(),
        null,
        null
    );

    when(kafkaTemplate.send(eq("orders.created"), eq("99"), eq(payload)))
        .thenReturn(CompletableFuture.completedFuture(null));

    publisher.publish(outboxEvent);

    verify(kafkaTemplate).send("orders.created", "99", payload);
}

This is a very good adapter test because it validates the contract between the outbox payload and Kafka publishing.

3. Persistence test

OutboxEventPersistenceAdapterTest verifies that:

an outbox event can be saved,
it is returned by findProcessableEvents,
it transitions to PUBLISHED after markPublished.

@Test
void shouldPersistAndTransitionOutboxEvents() {
    UUID id = UUID.fromString("11111111-1111-1111-1111-111111111111");

    outboxEventPersistenceAdapter.save(new OutboxEvent(
        id,
        "ORDER",
        "1",
        "ORDER_CREATED",
        "{\"orderId\":1}",
        OutboxStatus.PENDING,
        OffsetDateTime.parse("2026-03-24T10:15:30Z"),
        null,
        null
    ));

    assertThat(outboxEventPersistenceAdapter.findProcessableEvents(10)).hasSize(1);

    outboxEventPersistenceAdapter.markPublished(id);

    assertThat(outboxEventPersistenceAdapter.findAll())
        .singleElement()
        .extracting(OutboxEvent::status)
        .isEqualTo(OutboxStatus.PUBLISHED);
}

This test is important because the outbox pattern is not only about producing messages. It is also about tracking delivery state in a reliable way.

4. Kafka integration test

The most interesting test is OutboxPublisherKafkaIntegrationTest.

It:

inserts a pending outbox event,
invokes outboxPublisher.publishPendingEvents(),
consumes the record from Kafka,
verifies the payload,
verifies the outbox status became PUBLISHED.

@Test
void shouldPublishPendingOutboxEventToKafka() throws Exception {
    OrderCreatedEvent payload = new OrderCreatedEvent(
        99L,
        1L,
        "Default User",
        OrderStatus.CREATED,
        new BigDecimal("70.90"),
        OffsetDateTime.parse("2026-03-24T12:00:00Z"),
        List.of(new OrderCreatedItemEvent(
            10L,
            "Notebook",
            2,
            new BigDecimal("12.50"),
            new BigDecimal("25.00")
        ))
    );

    UUID eventId = UUID.randomUUID();

    outboxEventPort.save(new OutboxEvent(
        eventId,
        "ORDER",
        "99",
        "ORDER_CREATED",
        objectMapper.writeValueAsString(payload),
        OutboxStatus.PENDING,
        OffsetDateTime.now(),
        null,
        null
    ));

    try (KafkaConsumer<String, String> consumer = new KafkaConsumer<>(consumerProperties())) {
        consumer.subscribe(List.of(topic));

        outboxPublisher.publishPendingEvents();

        ConsumerRecord<String, String> publishedRecord = pollSingleRecord(consumer);

        assertThat(publishedRecord.key()).isEqualTo("99");

        OrderCreatedEvent publishedEvent =
            objectMapper.readValue(publishedRecord.value(), OrderCreatedEvent.class);

        assertThat(publishedEvent.orderId()).isEqualTo(99L);

        assertThat(outboxEventPort.findAll())
            .filteredOn(event -> event.id().equals(eventId))
            .singleElement()
            .extracting(OutboxEvent::status)
            .isEqualTo(OutboxStatus.PUBLISHED);
    }
}

This is the kind of test that gives confidence in the whole outbox flow end to end.

What this project teaches well

This repository is a strong example because it shows that the outbox pattern is not just “save event in a table.”

It also includes:

a dedicated outbox model,
clear application ports,
a scheduled publisher,
explicit status transitions,
Kafka integration,
persistence tests,
end-to-end integration coverage.

In other words, it demonstrates the pattern as an operational workflow, not just as a conceptual diagram.

Possible improvements

Even though the implementation is already solid, there are a few natural next steps:

Add retry count and backoff metadata to the outbox table.
Add dead-letter handling for repeatedly failing events.
Consider CDC with Debezium instead of polling when throughput grows.
Add observability metrics for pending, published, and failed events.
Make idempotency explicit on the consumer side as well.

These are suggestions on top of an implementation that is already well-structured. The current code already provides a good baseline for production-minded design.

Final thoughts

The best thing about this repository is that it uses the outbox pattern the way it should be used in a hexagonal architecture:

the use case creates business data and the outbox entry in the same transaction,
the application layer depends on ports,
the Kafka adapter is isolated,
the publisher is responsible for delivery and state transition,
and the tests validate the behavior from unit to integration level.

That makes allanroberto18/sb-kafka-producer-sample a much better study case than a simple “producer sends a message” demo. It shows how to build a reliable event publication flow with Spring Boot, Kafka, and Hexagonal Architecture.

Handle consumers: From Outbox to Email Delivery: Extending the Kafka Flow in Spring Boot

Improve the interaction with Stream AI Responses

Allan Roberto — Sun, 22 Mar 2026 23:28:44 +0000

I had a Spring Boot API talking to AI providers, and at first it did the most obvious thing: send the prompt, wait for the model to finish, and then return the full response as JSON.

It worked.

But it also felt wrong.

When you are dealing with AI-generated text, waiting several seconds for a complete response is a pretty bad experience. The model is already producing tokens progressively, but the API was hiding that and making the client wait for everything. So I decided to fix that and add proper streaming support.

This post is about that change.

Not a giant rewrite. Just a practical refactor to make AI responses feel alive instead of delayed.

The original problem

The first version of the endpoint was synchronous. The flow was basically:

Receive the prompt
Call the AI provider
Wait for the entire answer
Return one JSON response

That is simple, but it creates an awkward UX. Even when the model is generating steadily, the user sees nothing until the very end.

For normal CRUD APIs, that is fine.
For AI, it is not.

People expect text to appear as it is generated. Once you have used ChatGPT, Claude, or Ollama in a streaming UI, it is hard to go back.

The goal

I wanted the backend to expose a streaming endpoint so the frontend could start rendering text immediately.

At the same time, I did not want the implementation to become provider-specific spaghetti.

The app already supported more than one provider, so the solution had to work in a way that kept the service layer clean.

That led to two decisions:

Expose streaming through a dedicated endpoint
Make both AI clients implement the same streaming contract

Adding a streaming endpoint

I kept the normal JSON endpoint and added a second one for streaming.

The streaming endpoint returns text/event-stream and uses Spring’s SseEmitter:

@PostMapping(path = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter stream(@Valid @RequestBody ChatPromptRequest body) {
  String prompt = body.prompt().trim();
  SseEmitter emitter = new SseEmitter(0L);

  Thread.ofVirtual().start(() -> {
    try {
      chatService.stream(prompt, chunk -> sendChunk(emitter, chunk));
      emitter.complete();
    } catch (Exception exception) {
      emitter.completeWithError(exception);
    }
  });

  return emitter;
}

What I like about this approach is that it is pretty direct.
The controller does not need to know how Ollama or Claude stream internally. It only knows that chunks are coming in, and it forwards those chunks to the client as SSE events.

Each chunk is emitted like this:

emitter.send(SseEmitter.event().name("chunk").data(chunk));

So the frontend receives a stream that looks like:

event: chunk
data: Hello

event: chunk
data: world

That is very different from returning a JSON array. This is actual streaming, not "collect everything and send it later in a different shape."

The tricky part: providers do not stream the same way

This was the part that mattered most in the refactor.

The application supports both Ollama and Claude, but they do not return streamed data in the same format.

Ollama streams newline-delimited JSON.

Claude streams Server-Sent Events containing event types and payloads.

So even though both are "streaming," they are not interchangeable at the raw HTTP level.

If I pushed that difference too high in the application, the controller and service code would get messy fast. I wanted the rest of the app to think in terms of text chunks, not provider-specific wire formats.

So I added a common method to the client contract:

public interface LlmClient {
  ChatResponse chat(ChatRequest request);

  default void streamChat(ChatRequest request, Consumer<String> onChunk) {
    throw new UnsupportedOperationException("Streaming is not supported by this provider");
  }
}

That gave both clients the same responsibility: take a request, read the upstream stream, and call onChunk every time there is new text.

Once that was in place, the service and controller stayed simple.

Handling Ollama streaming

For Ollama, the request needed to enable streaming explicitly:

Map<String, Object> body = Map.of(
    "model", model,
    "prompt", request.prompt(),
    "stream", true
);

Then the client reads the response stream line by line, parses each JSON object, and extracts the response field.
Conceptually, it works like this:

Read one line
Parse it as JSON
If it has text in response, forward it
Repeat until the stream ends

That maps nicely to a Consumer<String> callback.

Handling Claude streaming

Claude needed a different implementation because its stream is SSE-based upstream.

That means the code has to deal with:

Event names
data: lines
Event boundaries
Content deltas

In practice, I only wanted the actual text fragments, so the Claude client listens for the right event type and extracts the text delta before forwarding it.

Same application-level behavior, different provider-level parsing.

That is the part I think was worth doing carefully. The point was not to pretend both providers behave the same. The point was to hide those differences behind one consistent interface for the rest of the app.

Sharing the parsing behavior without overengineering it

I also pulled the repetitive stream parsing logic into a small shared helper.

Not a big framework. Just a utility to handle:

JSON-line iteration
SSE event iteration

That helped keep the provider clients focused on provider logic instead of low-level stream mechanics.

This was one of those refactors that made the code easier to read immediately. Both clients still do different things, but now the differences are easier to spot because the noise is lower.

What the frontend should do

One thing that is easy to get wrong: this endpoint is a POST, so the frontend should not use EventSource.
EventSource only works well with GET.

Since the streaming endpoint is POST /api/chat/stream, the frontend should use fetch() and read the response body as a stream.

That is the right match for this backend.

So the flow on the frontend becomes:

Send the prompt with fetch
Read chunks from response.body
Parse SSE frames
Append each chunk event to the displayed answer

That gives the user progressive rendering without waiting for the model to finish the entire response.

And honestly, that one change makes the app feel much faster, even if the total generation time is exactly the same.

A couple of small supporting improvements

The main work here was streaming, but while I was in the code I cleaned up two smaller things that made the API nicer.

First, I replaced the request payload from Map<String, String> with a proper record:

public record ChatPromptRequest(
    @NotBlank(message = "prompt must not be blank")
    String prompt
) {
}

and used @Valid in the controller.

That is a lot better than manually fishing values out of a map. The request contract is clearer, validation is built in, and the OpenAPI docs become more accurate automatically.
Second, I added a small global exception handler returning ProblemDetail for validation failures and unexpected server errors.

That was not directly about streaming, but it made the endpoints behave more consistently, especially when bad input is sent or something fails during processing.

I would still treat those as side improvements, though. The main story here is the streaming refactor.

What changed in practice

Before this work, the API waited for the full AI answer and returned one final payload.

After the refactor:

The API can stream text progressively to the client
Ollama and Claude both support the same application-level streaming feature
The controller does not care about provider-specific stream formats
The frontend can render the answer as it arrives

That is the kind of change I like: it improves the user experience, but it also improves the shape of the backend code.

Usually you only get one or the other.

Final thought

Streaming sounds like a UI feature, but it is really an API design decision too.

If the backend hides the model’s incremental output, the frontend has no chance to create a responsive experience.

Once I changed the API to treat streamed tokens as a first-class concern, the whole flow started making more sense.

The nice part is that the code did not need to become complicated to support it. It just needed a cleaner contract.

And that, more than anything, was the real improvement.

Running LLMs Locally with Ollama: Benefits, Limitations, and Hardware Reality

Allan Roberto — Thu, 19 Mar 2026 13:08:39 +0000

Running LLMs Locally with Ollama: Benefits, Limitations, and Hardware Reality

Allan Roberto ・ Mar 19

#ai #programming #tutorial

Using Ollama Locally to Save Money

Allan Roberto — Thu, 19 Mar 2026 13:08:19 +0000

Using Ollama Locally to Save Money (and When to Switch to Cloud AI)

Allan Roberto ・ Mar 19

#ai #java #springboot #programming

Using Ollama Locally to Save Money (and When to Switch to Cloud AI)

Allan Roberto — Thu, 19 Mar 2026 12:57:51 +0000

🚀 Introduction

AI is powerful — but it can also become very expensive very quickly.

If you’re building an AI-powered application, you’ve probably faced this:

💸 “Why is my OpenAI bill already this high?”

This is exactly where Ollama + Cloud AI hybrid strategy shines.

🧠 The Strategy

👉 Use Ollama locally for development
👉 Use Cloud AI provider in production

This approach gives you the best of both worlds.

💰 Why Use Ollama for Development?

1. Zero API Costs

Instead of:

$0.01 per request × thousands of tests = 💸

You get:

Unlimited local testing = $0

2. Faster Feedback Loop

No network latency
No rate limits
No API keys

3. Safe Experimentation

You can:

Try prompts freely
Test edge cases
Debug without worrying about cost

☁️ Why NOT Use Ollama in Production?

Even though it’s tempting… here’s the reality:

❌ Scaling Issues

Hard to scale horizontally
Requires heavy infrastructure

❌ Performance Constraints

Slower than optimized cloud inference
Depends on your hardware

❌ Maintenance Overhead

You now manage:

Models
Updates
Infrastructure

🔥 Why Use Cloud AI in Production?

Let’s say you choose OpenAI, Anthropic, or similar.

✔ Scalability

Handles thousands of requests automatically

✔ Performance

Optimized GPUs
Fast inference

✔ Reliability

High availability
SLAs

🧩 Architecture Example

[DEV]
Frontend → Spring Boot → Ollama (local)

[PROD]
Frontend → Spring Boot → Cloud AI Provider

Even better:

Spring Boot
   ├── Local Profile → Ollama
   └── Prod Profile → OpenAI / Anthropic

🔄 Smart Switching Strategy

Use environment-based configuration:

spring:
  profiles:
    active: local

Then:

local → Ollama
prod → OpenAI

💡 Real Benefit

You:

Save money during development
Keep production scalable
Avoid vendor lock-in

🤯 The Hidden Advantage

This approach forces you to:
Design abstraction layers
Decouple AI provider from business logic
Which is great architecture practice.

🧠 My Take

Ollama is not just a tool — it’s a cost-control strategy.

Use it to:

Build locally
Experiment safely
Avoid unnecessary expenses

Then switch to cloud AI when:

Performance matters
Scale matters
Reliability matters

🚀 Final Thought

The best AI architecture today isn’t:

Local OR Cloud

It’s:

Local AND Cloud — each in the right place

Running LLMs Locally with Ollama: Benefits, Limitations, and Hardware Reality

Allan Roberto — Thu, 19 Mar 2026 12:46:16 +0000

🚀 Introduction

Large Language Models (LLMs) are everywhere — but most developers rely heavily on cloud providers like OpenAI, Anthropic, or Azure.

But what if you could run models locally on your machine?

That’s where Ollama comes in.

In this article, I’ll explain:

Why you should consider using Ollama
When it makes sense
The real limitations (especially GPU vs CPU)
Lessons learned from using it in a Spring Boot project

🤖 What is Ollama?

Ollama is a tool that allows you to run LLMs locally with a simple CLI/API.

Example:

ollama run llama3

Or via HTTP:

POST http://localhost:11434/api/generate

It abstracts away:

Model downloads
Runtime configuration
Inference execution

💡 Why Use Ollama?

1. 💰 Zero Cost for Development

No API calls → no billing → perfect for:

Local testing
Prototyping
Feature validation

2. 🔒 Privacy & Data Control

Your data never leaves your machine:

Great for sensitive use cases
Useful for regulated environments

3. ⚡ Offline Capability

You can run LLMs:

Without internet
Without external dependencies

4. 🧪 Faster Iteration Loop

No network latency:

Immediate responses
Easier debugging

⚠️ The Reality: Hardware Matters A LOT

This is where most developers get surprised.

🖥️ CPU vs GPU

Resource	Experience
CPU only	Slow inference (seconds per response)
GPU (8GB+)	Much faster, usable in real apps
High-end GPU	Near real-time performance

🧠 Model Size vs RAM

Model	RAM Requirement
7B	~4–8 GB
13B	~10–16 GB
70B	🔥 Not for laptops

⚡ Real Limitations

If you're using:

A basic notebook (8–16GB RAM, no GPU) → expect:
- Slow responses
- Limited models
- Occasional crashes

If you have:

Apple Silicon (M1/M2/M3) → surprisingly good performance
NVIDIA GPU → best experience

🧩 Using Ollama in a Spring Boot Project

In your repository, the idea is simple:

Spring Boot → HTTP call → Ollama (localhost) → Model response

This gives you:

Full control over AI behavior
No dependency on external providers during development

🤯 Key Takeaways

✔ Ollama is amazing for development
✔ It removes cost and external dependencies
✔ BUT your hardware defines your experience

🧠 My Take

Ollama is not a replacement for cloud AI — it’s a development superpower.

Use it to:

Experiment fast
Validate ideas
Build locally

But don’t expect production-level performance without serious hardware.

Building Semantic Search with Spring Boot, PostgreSQL, and pgvector (RAG Retrieval)

Allan Roberto — Sun, 15 Mar 2026 12:23:24 +0000

In the previous article, we built the indexing pipeline for our knowledge base:

documents are saved
content is split into chunks
embeddings are generated
vectors are stored in PostgreSQL using pgvector

But indexing is only half of the system.

The real value comes when users can ask questions and receive answers based on the indexed knowledge.

In this article we will implement the retrieval side of the architecture using Spring Boot.

By the end of this tutorial, our system will support:

receiving a user question
converting the question into an embedding
searching the vector database for similar chunks
building a prompt with contextual information
sending that prompt to an AI client
returning a grounded response

This architecture is commonly known as Retrieval-Augmented Generation (RAG).

Understanding the Retrieval Flow

Once documents are indexed, the query flow looks like this:

User question
   ↓
Convert question into embedding
   ↓
Vector similarity search in PostgreSQL
   ↓
Retrieve most relevant chunks
   ↓
Build prompt with context
   ↓
Send prompt to AI model
   ↓
Return answer

An important detail is that vectors are not sent to the AI model.

Vectors are used only to retrieve the most relevant text.

The AI receives plain text chunks as context.

Step 1 — Question Request DTO

First we define the request used by the semantic search endpoint.

package com.example.knowledgebase.api;

import jakarta.validation.constraints.NotBlank;

public record AskQuestionRequest(
        @NotBlank String question
) {}

Response DTO:

package com.example.knowledgebase.api;

import java.util.List;

public record AskQuestionResponse(
        String question,
        String answer,
        List<String> contextChunks
) {}

Returning the context chunks is useful for debugging and understanding how retrieval works.

Step 2 — Vector Similarity Query

The similarity search happens in the knowledge_document_chunk table.

We extend our repository with a native query using pgvector.

package com.example.knowledgebase.repository;

import com.example.knowledgebase.domain.KnowledgeDocumentChunk;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;

import java.util.List;

@Repository
public interface KnowledgeDocumentChunkRepository extends JpaRepository<KnowledgeDocumentChunk, Long> {
  List<KnowledgeDocumentChunk> findByDocumentIdOrderByChunkIndexAsc(Long documentId);

  @Query(value = """
      SELECT
          id,
          document_id AS documentId,
          chunk_index AS chunkIndex,
          chunk_text AS chunkText,
          embedding <-> CAST(:embedding AS vector) AS distance
      FROM knowledge_document_chunk
      ORDER BY embedding <-> CAST(:embedding AS vector)
      LIMIT :limit
      """, nativeQuery = true)
  List<SimilarChunkProjection> searchTopK(
      @Param("embedding") String embedding,
      @Param("limit") int limit
  );

  void deleteByDocumentId(Long documentId);
}

This query uses the pgvector distance operator:

embedding <-> query_vector

It returns the nearest vectors first, meaning the most semantically similar chunks.

Step 3 — Projection for Query Results

Instead of loading the full entity, we use a projection.

package com.example.knowledgebase.repository;

public interface SimilarChunkProjection {

    Long getId();

    Long getDocumentId();

    Integer getChunkIndex();

    String getChunkText();

    Double getDistance();
}

This keeps the query lightweight.

Step 4 — Embedding Formatter

PostgreSQL expects vectors formatted like this:

[0.12,0.34,0.98,...]

We add a small helper component.

package com.example.knowledgebase.service;

import org.springframework.stereotype.Component;

@Component
public class VectorFormatter {

    public String toPgVector(float[] embedding) {

        StringBuilder builder = new StringBuilder("[");
        for (int i = 0; i < embedding.length; i++) {

            builder.append(embedding[i]);

            if (i < embedding.length - 1) {
                builder.append(",");
            }
        }

        builder.append("]");

        return builder.toString();
    }
}

Step 5 — Retrieval Service

This service handles semantic retrieval.

package com.example.knowledgebase.service;

import com.example.knowledgebase.repository.KnowledgeDocumentChunkRepository;
import com.example.knowledgebase.repository.SimilarChunkProjection;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
@RequiredArgsConstructor
public class RetrievalService {

    private final EmbeddingService embeddingService;
    private final KnowledgeDocumentChunkRepository chunkRepository;
    private final VectorFormatter vectorFormatter;

    public List<String> retrieveRelevantChunks(String question, int topK) {

        float[] questionEmbedding = embeddingService.generateEmbedding(question);

        String vector = vectorFormatter.toPgVector(questionEmbedding);

        List<SimilarChunkProjection> results =
                chunkRepository.searchTopK(vector, topK);

        return results.stream()
                .map(SimilarChunkProjection::getChunkText)
                .toList();
    }
}

The retrieval logic is straightforward:

embed the question
run similarity search
return the chunk text

Step 6 — Prompt Builder

Next we build the prompt that will be sent to the AI model.

package com.example.knowledgebase.service;

import org.springframework.stereotype.Component;

import java.util.List;

@Component
public class PromptBuilder {

    public String build(String question, List<String> contextChunks) {

        StringBuilder prompt = new StringBuilder();

        prompt.append("""
                You are an assistant for a knowledge base.
                Answer only using the context below.
                If the answer is not present in the context, say you do not know.

                Context:
                """);

        for (int i = 0; i < contextChunks.size(); i++) {

            prompt.append("\n[")
                    .append(i + 1)
                    .append("] ")
                    .append(contextChunks.get(i));
        }

        prompt.append("\n\nUser question:\n");
        prompt.append(question);

        prompt.append("\n\nAnswer:");

        return prompt.toString();
    }
}

This is a key concept of RAG:

the model receives relevant context extracted from your database.

Step 7 — AI Client Abstraction

To keep the architecture flexible, we define an AI client interface.

package com.example.knowledgebase.service;

public interface AiClient {

    String ask(String prompt);

}

Later you could implement this with:

OpenAI
Azure OpenAI
Anthropic
Ollama
a local LLM

For this tutorial we use a simple mock implementation.

Step 8 — Fake AI Client

package com.example.knowledgebase.service;

import org.springframework.stereotype.Service;

@Service
public class FakeAiClient implements AiClient {

    @Override
    public String ask(String prompt) {

        return """
                Fake AI response.
                In a real system, this prompt would be sent to an LLM provider.
                """;
    }
}

This keeps the tutorial runnable without requiring external APIs.

Step 9 — Semantic Search Service

Now we combine everything into a service.

package com.example.knowledgebase.service;

import com.example.knowledgebase.api.AskQuestionResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
@RequiredArgsConstructor
public class SemanticSearchService {

    private static final int TOP_K = 3;

    private final RetrievalService retrievalService;
    private final PromptBuilder promptBuilder;
    private final AiClient aiClient;

    public AskQuestionResponse ask(String question) {

        List<String> contextChunks =
                retrievalService.retrieveRelevantChunks(question, TOP_K);

        String prompt = promptBuilder.build(question, contextChunks);

        String answer = aiClient.ask(prompt);

        return new AskQuestionResponse(
                question,
                answer,
                contextChunks
        );
    }
}

Step 10 — REST Endpoint

Finally we expose the semantic search endpoint.

package com.example.knowledgebase.api;

import com.example.knowledgebase.service.SemanticSearchService;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/questions")
@RequiredArgsConstructor
public class SemanticSearchController {

    private final SemanticSearchService semanticSearchService;

    @PostMapping
    public AskQuestionResponse ask(
            @Valid @RequestBody AskQuestionRequest request
    ) {

        return semanticSearchService.ask(request.question());
    }
}

Now users can ask questions via HTTP.

Testing the Semantic Search

Example request:

POST /questions
Content-Type: application/json
{
  "question": "How does pgvector work with Spring Boot?"
}

Example response:

{
  "question": "How does pgvector work with Spring Boot?",
  "answer": "Fake AI response. In a real system, this prompt would be sent to an LLM provider.",
  "contextChunks": [
    "PostgreSQL can be used as a vector database using pgvector.",
    "Spring Boot can index documents by chunking content.",
    "Embeddings allow semantic similarity search."
  ]
}

Notice how the response includes the context used by the AI.

Why This Architecture Matters

This pattern powers many modern AI systems:

internal knowledge assistants
AI copilots
support automation tools
enterprise search platforms

By combining:

vector search
retrieved context
LLM generation

we create systems that produce grounded answers instead of hallucinations.

Final Architecture

At this point our system supports both sides of RAG.

Indexing pipeline

Document
→ Chunking
→ Embeddings
→ Stored in pgvector

Retrieval pipeline

Question
→ Embedding
→ Vector similarity search
→ Context retrieval
→ Prompt building
→ AI response

This is the foundation of many real-world AI applications.

Hot to

Conclusion

In this article we implemented the retrieval layer of a RAG system using Spring Boot and PostgreSQL.

Our application can now:

embed user questions
perform vector similarity search
retrieve relevant document chunks
construct contextual prompts
generate AI responses

Together with the previous article, we now have a complete knowledge base architecture powered by vector search.

Meaning: How Data Vectorization Powers AI
Turning PostgreSQL Into a Vector Database with Docker
Indexing Knowledge Base Content with Spring Boot and pgvector
Building Semantic Search with Spring Boot, PostgreSQL, and pgvector (RAG Retrieval)
How I Added LangChain4j Without Letting It Take Over My Spring Boot App

Project Here

Simple outbox and quarkus example

Allan Roberto — Thu, 12 Mar 2026 19:29:48 +0000

Implementing the Transactional Outbox Pattern with Quarkus

Allan Roberto ・ Mar 12

#quarkus #java #backend #architecture

Implementing the Transactional Outbox Pattern with Quarkus

Allan Roberto — Thu, 12 Mar 2026 19:29:27 +0000

Introduction

In distributed systems, one of the hardest problems is guaranteeing data consistency when publishing events.

Imagine the following scenario:

Your API saves data in the database.
It publishes an event to a message broker (Kafka, RabbitMQ, etc).

What happens if:

The database transaction succeeds
But the event fails to publish?

Now your system is in an inconsistent state.

This is exactly the problem the Transactional Outbox Pattern solves.

In this article, we will explore:

The problem of dual writes
How the Outbox Pattern solves it
A practical implementation using Quarkus
A working sample project

Repository:

👉 https://github.com/allanroberto18/outbox-sample-api

The Dual Write Problem

When an application performs two operations:

1️⃣ Save data
2️⃣ Publish an event

We call this a dual write problem.

Example:

@Transactional
public void createOrder(Order order) {

    orderRepository.persist(order);

    eventPublisher.publish(
        new OrderCreatedEvent(order.getId())
    );
}

If the event fails to publish, the database is already committed.

This leads to:

❌ Lost events
❌ Inconsistent services
❌ Broken microservice workflows

The Outbox Pattern

The Outbox Pattern solves this problem by storing events in the same database transaction as the business data.

Instead of publishing directly to a broker, we do this:

1️⃣ Save business data
2️⃣ Save event in an outbox table
3️⃣ A background worker publishes the event

Flow

API receives request
Database transaction saves:
Business entity
Outbox event
Worker reads events from Outbox
Events are published to message broker
Event marked as processed

This guarantees event delivery without losing consistency.

The pattern ensures events are published only if the database transaction succeeds.

Project Overview

This repository demonstrates a simple implementation using Quarkus.

👉 https://github.com/allanroberto18/outbox-sample-api

Technologies used:

Quarkus
Java
JPA / Hibernate
Transactional Outbox Pattern

Quarkus is a Java framework optimized for cloud-native applications and microservices.

Creating the Outbox Event

First we create a table responsible for storing events.

Example entity:

@Entity
@Table(name = "outbox_event")
public class OutboxEvent {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  public Long id;

  @Column(name = "event_type", nullable = false, length = 120)
  public String eventType;

  @Column(name = "payload", nullable = false, columnDefinition = "TEXT")
  public String payload;

  @Enumerated(EnumType.STRING)
  @Column(nullable = false, length = 20)
  public OutboxEventStatus status;

  @Column(nullable = false)
  public int attempts;

  @Column(name = "error_message", length = 1000)
  public String errorMessage;

  @Column(name = "last_error_at")
  public LocalDateTime lastErrorAt;

  @Column(name = "next_attempt_at")
  public LocalDateTime nextAttemptAt;

  @Column(name = "max_attempts", nullable = false)
  public int maxAttempts;

  @Column(name = "created_at", nullable = false)
  public LocalDateTime createdAt;

  @Column(name = "processed_at")
  public LocalDateTime processedAt;
}

This table acts as a buffer between the database and the message broker.

Saving Business Data + Event

Inside the same transaction we save:

The entity
The outbox event

Example:

// from RegisterUserUseCase
@Transactional
public UserResponse execute(CreateUserRequest request) {
  if (userRepository.existsByUsername(request.username())) {
    throw new DuplicateUsernameException(request.username());
  }

  UserEntity user = new UserEntity();
  user.firstName = request.firstName();
  user.lastName = request.lastName();
  user.username = request.username();
  user.password = passwordHasher.hash(request.password());
  user.enabled = false;

  try {
    userRepository.persist(user);
    userRepository.flush();
  } catch (PersistenceException ex) {
    if (isUniqueViolation(ex)) {
      throw new DuplicateUsernameException(request.username());
    }  
    throw ex;
  }

  // save outbox
  userActivationOutboxService.publishUserActivationEmail(user);

  return UserResponse.fromEntity(user);
}

// from UserActivationOutboxService
public void publishUserActivationEmail(UserEntity user) {
  OutboxEventEntity outboxEvent = new OutboxEventEntity();
  outboxEvent.eventType = EVENT_TYPE_USER_ACTIVATION_EMAIL;
  outboxEvent.payload = toPayload(user);
  outboxEvent.maxAttempts = maxAttempts;
  outboxRepository.persist(outboxEvent);
}

Now both operations happen atomically.

If the transaction fails:

❌ No user saved
❌ No event created

Event Publisher Worker

A background job periodically reads unprocessed events.

Example:

@ApplicationScoped
public class OutboxDispatcherService {

  @Inject
  DispatchOutboxUseCase dispatchOutboxUseCase;

  @Scheduled(every = "{outbox.dispatch.every}")
  @RunOnVirtualThread
  void scheduledDispatch() {
    dispatchPending();
  }

  public void dispatchPending() {
    dispatchOutboxUseCase.execute();
  }
}

This worker:

1️⃣ Reads pending events
2️⃣ Publishes them
3️⃣ Marks them as processed

Benefits of the Outbox Pattern

Using this pattern provides several advantages.

Reliability

Events are not lost.

Consistency

Database and event stream stay synchronized.

Fault Tolerance

If the broker is down, events stay in the database.

Scalability

Workers can scale horizontally.

Running the Project

Clone the repository:

git clone https://github.com/allanroberto18/outbox-sample-api

Run Quarkus in dev mode:

./mvn quarkus:dev

Quarkus dev mode enables live coding, allowing code changes without restarting the application.

When Should You Use the Outbox Pattern?

Use it when:

Building microservices
Publishing domain events
Integrating with Kafka / RabbitMQ
Ensuring eventual consistency

Avoid it when:

Systems are simple
No asynchronous communication exists

Final Thoughts

The Transactional Outbox Pattern is one of the most important patterns for building reliable distributed systems.

It solves the dual write problem and ensures:

✔ Consistent state
✔ Reliable event publishing
✔ Resilient microservices

If you want to explore a practical implementation, check the repository:

👉 https://github.com/allanroberto18/outbox-sample-api

DEV Community: Allan Roberto

How I Added LangChain4j Without Letting It Take Over My Spring Boot App

The architectural rule

What LangChain4j does here, and what it does not do

The indexing flow stays in the application core

LangChain4j is useful here because it is constrained

Retrieval still belongs to PostgreSQL

Prompt rendering is framework-assisted, not framework-owned

The fake models are not a shortcut anymore

One constraint that should stay explicit

Why this design works

From Outbox to Email Delivery: Extending the Kafka Flow in Spring Boot

Why not send the email directly in the consumer?

Step 1: consume the Kafka event and generate the email request

Step 2: store the invoice email and create a new outbox event

Building an invoice-like email

Step 3: dispatch the email from the outbox

Step 4: send the email and update the order

Retry support

Why I like this version better

Final thoughts

[Boost]

Outbox Pattern with Kafka and Hexagonal Architecture in Spring Boot

Outbox Pattern with Kafka and Hexagonal Architecture in Spring Boot

Why the Outbox Pattern matters

Hexagonal Architecture in the repository

The core of the pattern: CreateOrderService

The Outbox model

The publisher side

Kafka adapter

Why this implementation is good

Tests in the repository

1. Use case test

2. Kafka publisher unit test

3. Persistence test

4. Kafka integration test

What this project teaches well

Possible improvements

Final thoughts

Improve the interaction with Stream AI Responses

The original problem

The goal

Adding a streaming endpoint

The tricky part: providers do not stream the same way

Handling Ollama streaming

Handling Claude streaming

Sharing the parsing behavior without overengineering it

What the frontend should do

A couple of small supporting improvements

What changed in practice

Final thought

Related

Running LLMs Locally with Ollama: Benefits, Limitations, and Hardware Reality

Running LLMs Locally with Ollama: Benefits, Limitations, and Hardware Reality

Allan Roberto ・ Mar 19

Using Ollama Locally to Save Money

Using Ollama Locally to Save Money (and When to Switch to Cloud AI)

Allan Roberto ・ Mar 19

Using Ollama Locally to Save Money (and When to Switch to Cloud AI)

🚀 Introduction

🧠 The Strategy

💰 Why Use Ollama for Development?

1. Zero API Costs

2. Faster Feedback Loop

3. Safe Experimentation

☁️ Why NOT Use Ollama in Production?

❌ Scaling Issues

❌ Performance Constraints

❌ Maintenance Overhead

🔥 Why Use Cloud AI in Production?

✔ Scalability

✔ Performance

✔ Reliability

🧩 Architecture Example

🔄 Smart Switching Strategy

💡 Real Benefit

🤯 The Hidden Advantage

🧠 My Take

🚀 Final Thought

Running LLMs Locally with Ollama: Benefits, Limitations, and Hardware Reality

The core of the pattern: `CreateOrderService`