Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: An Event-Driven Order Pipeline

Design an event-driven order pipeline in Quarkus: orders, inventory and invoices connected by Kafka topics, with partitions, consumer groups, the outbox pattern and dead letters.

The bookshop API of the last project answers requests directly. Real systems also react to things that happened: an order was placed, so stock must be reserved, an invoice created, an email sent. If the order service called each of these over HTTP and waited, one slow or broken service would break checkout. This project builds the alternative with Kafka and Quarkus: services that communicate through events and stay independent.

You will design three services, pick topics and keys, write the Quarkus code, and then understand the two ideas that make such systems correct: idempotent consumers and the outbox pattern. The real Quarkus and Kafka code is read-only, and the TryIts model a broker with partitions and offsets, and the reliability patterns, in plain Java. Background: reactive messaging and the Kafka tutorial.

The design

flowchart LR
    API["order-service<br/>POST /orders"] -->|"order-placed"| T1[("topic: orders")]
    T1 --> INV["inventory-service"]
    T1 --> BILL["invoice-service"]
    INV -->|"stock-reserved / stock-rejected"| T2[("topic: stock")]
    BILL -->|"invoice-created"| T3[("topic: invoices")]
    T2 --> API
    T3 --> MAIL["notification-service"]

Each service owns its data and reacts to events. No service calls another directly.

Event Topic Key Producer Consumers
OrderPlaced orders order id order-service inventory, invoice
StockReserved / StockRejected stock order id inventory-service order-service
InvoiceCreated invoices order id invoice-service notification-service

The key matters. Kafka sends all records with the same key to the same partition, in order. Using the order id as key guarantees that events of one order are processed in the order they were produced, while different orders run in parallel on other partitions.

The order service

Java
@Path("/orders")
public class OrderResource {

    @Channel("orders-out") Emitter<Record<String, OrderPlaced>> emitter;

    @POST
    @Transactional
    public Response place(@Valid NewOrder request) {
        Order order = Order.create(request);          // status PENDING, persisted
        emitter.send(Record.of(order.id.toString(),
                new OrderPlaced(order.id, order.items(), order.totalCents())));
        return Response.accepted(Map.of("orderId", order.id, "status", "PENDING")).build();
    }
}
PROPERTIES
mp.messaging.outgoing.orders-out.connector=smallrye-kafka
mp.messaging.outgoing.orders-out.topic=orders
mp.messaging.outgoing.orders-out.key.serializer=org.apache.kafka.common.serialization.StringSerializer
mp.messaging.outgoing.orders-out.value.serializer=io.quarkus.kafka.client.serialization.ObjectMapperSerializer

The response is 202 Accepted, not 201: the order exists, but its outcome is not known yet. The client polls GET /orders/{id} or receives a notification.

The inventory service

Java
@ApplicationScoped
public class StockReservation {

    @Inject StockRepository stock;

    @Incoming("orders-in")
    @Outgoing("stock-out")
    @Blocking
    @Transactional
    public Record<String, StockResult> reserve(Record<String, OrderPlaced> in) {
        OrderPlaced order = in.value();
        if (stock.alreadyHandled(order.orderId())) {          // idempotent: duplicate delivery
            return Record.of(in.key(), stock.previousResult(order.orderId()));
        }
        boolean ok = stock.tryReserve(order.items());
        StockResult result = ok ? StockResult.reserved(order.orderId())
                                : StockResult.rejected(order.orderId(), "out of stock");
        stock.remember(order.orderId(), result);
        return Record.of(in.key(), result);
    }
}
PROPERTIES
mp.messaging.incoming.orders-in.connector=smallrye-kafka
mp.messaging.incoming.orders-in.topic=orders
mp.messaging.incoming.orders-in.group.id=inventory-service
mp.messaging.incoming.orders-in.failure-strategy=dead-letter-queue

Each service uses its own group.id. Within one group, the partitions of a topic are shared between the running instances (scale-out); across groups, every group sees every record (publish and subscribe). That is how inventory and invoice both receive OrderPlaced.

Event-driven building blocks

Key Same key, same partition, in order.
Consumer group Instances share partitions.
Offset Where each group has read to.
Dead letter Park poison messages.

Kafka remembers events, so new consumers can replay.

1 / 2
Java Stand-in: partitions, keys and consumer groups

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that all three order-1 events appear in the same partition and in production order, and that each group has its own offsets.

Problem 1: the dual write

Look at OrderResource.place again. It writes to the database and sends an event. These are two systems with no shared transaction. If the database commit succeeds and the application crashes before the send, the order exists but nobody ever hears of it. If the send succeeds and the commit fails, the world is told about an order that does not exist. This is the dual-write problem.

The outbox pattern fixes it by writing the event into an outbox table in the same database transaction as the order. A separate relay then publishes outbox rows to Kafka and marks them sent. The event can be published twice (the relay might crash after sending and before marking), which is fine because consumers are idempotent. Quarkus supports this with the Debezium extension (quarkus-debezium or the Kafka Connect connector) that reads the outbox table from the database log.

Java
@Transactional
public Order place(NewOrder request) {
    Order order = Order.create(request);          // INSERT INTO orders
    OutboxEvent.of("OrderPlaced", order).persist();   // INSERT INTO outbox, same transaction
    return order;
}

Problem 2: duplicates and poison messages

Kafka delivery to a consumer is at-least-once. A consumer that crashes after doing the work but before committing its offset will see the message again. A poison message (malformed or hitting a bug) makes a consumer fail again and again. The pipeline needs idempotent handling plus a bounded number of retries, then the dead-letter topic.

Java Stand-in: outbox relay, idempotent consumer and dead letters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The duplicate was absorbed, the poison message was parked, and the stock is correct. Those two behaviors are what make an event-driven system safe to operate.

Problem 3: when a step fails halfway

Orders involve several services, and there is no distributed transaction. A saga coordinates them with events and compensating actions: if the invoice service cannot create an invoice after the inventory already reserved stock, it publishes InvoiceFailed; the inventory service reacts by releasing the stock. Each service knows only its own step and its own undo. For a simple flow, choreography (services react to each other's events, as in this project) is enough; for a long flow, an orchestrator service that tracks the state is easier to follow and to debug.

Testing the pipeline

Use the in-memory connector from mocks and test profiles for unit-level tests of each service. Use Dev Services Kafka in a few @QuarkusTests to prove serialization and consumer-group configuration. Test the failure paths explicitly: send the same event twice, send a malformed one, and check the counts.

Operating it

  • Watch consumer lag (how far a group is behind the end of a partition). Growing lag means consumers are too slow or stuck.
  • Alert on dead-letter topic size, and write a small tool to inspect and replay it.
  • Version your event schemas (Apicurio or Confluent Schema Registry) and only make backward-compatible changes: add optional fields, never rename.
  • Set partition counts for the parallelism you want; you can add partitions later, but keys then map differently.
  • Use tracing: the trace context travels in Kafka record headers, so one trace spans the whole pipeline.

Extension challenges

  1. Add the notification service and send an email (a logged line) on InvoiceCreated.
  2. Implement the compensation: InvoiceFailed releases the reserved stock.
  3. Add an orders-dlq consumer that stores failures in a table and exposes GET /dead-letters.
  4. Write a test that publishes the same OrderPlaced twice and asserts stock drops once.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why use the order id as the Kafka record key?

    Per-key ordering is guaranteed because one partition is read by one consumer of the group in order.
  2. 2. What problem does the outbox pattern solve?

    Writing the event to a table in the same transaction guarantees it is not lost, and a relay publishes it later.
  3. 3. Two services use different group.id values for the same topic. What happens?

    Groups are independent subscribers; within a group, partitions are divided among instances.
  4. 4. How should a consumer handle a message it has already processed?

    At-least-once delivery means duplicates happen; idempotent handling makes them harmless.

Summary

  • Events decouple services; keys give per-entity ordering; consumer groups give scaling and fan-out.
  • The outbox pattern solves the dual write; idempotent consumers solve duplicates; dead letters park poison messages.
  • Sagas with compensations replace distributed transactions.
  • Monitor lag and dead-letter size, version event schemas, and test failure paths.

Next: Migrating from Spring Boot to Quarkus