Learn Apache Kafka and Spring Kafka by following one event through a production-inspired ride-dispatch workflow.
RouteX is a Java 21 / Spring Boot application that accepts ride requests over HTTP, publishes them to Kafka, assigns an in-memory demo driver, publishes an assignment event, and consumes that event for a console notification. The project deliberately keeps the business domain small so that Kafka behaviour stays visible.
In RouteX, ride intake does not call matching or notification directly. It publishes a RideRequestedEvent to ride-requested. Matching and notification are independent Kafka consumers with their own progress and failure handling. This demonstrates the event-driven boundary used when services must evolve, scale, or recover independently.
| Area | Demonstrated in RouteX |
|---|---|
| Event pipeline | HTTP request → ride-requested → matching → driver-assigned → notification |
| Topics and keys | Three application topics; records keyed by rideId |
| Parallel consumption | Three matching listener containers for three input partitions |
| Delivery control | Manual acknowledgement after successful listener work |
| Reliability | Fixed retry backoff and explicit dead-letter-topic recovery |
| Operations | Local KRaft Kafka, Kafka UI, rebalance logging, and Actuator endpoints |
flowchart LR
C[HTTP client] --> R[RideRequestController]
R -->|RideRequestedEvent<br/>key: rideId| RR[ride-requested<br/>3 partitions]
RR -->|driver-matching-group<br/>concurrency: 3| M[DriverMatchingConsumer]
M --> S[DriverAssignmentService]
S --> P[DriverAssignmentProducer]
P -->|DriverAssignmentEvent<br/>key: rideId| DA[driver-assigned<br/>3 partitions]
DA -->|notification-group| N[Notification consumer]
M -->|failure-test| E[DefaultErrorHandler]
E -->|3 retries, 2 seconds| D[ride-requested-dlt]
D -->|routex-dlt-monitor| DL[DeadLetterConsumer]
sequenceDiagram
participant H as HTTP client
participant R as RouteX
participant K as Kafka
participant M as Matching
participant N as Notification
H->>R: POST /rides/requests
R->>K: RideRequestedEvent (rideId key)
R-->>H: 202 Accepted
K->>M: ride-requested record
M->>K: DriverAssignmentEvent (rideId key)
K->>N: driver-assigned record
Java 21 · Spring Boot 3.5.16 · Spring for Apache Kafka · Confluent Platform 7.9.0 · Docker Compose · Kafka UI · Maven
docker compose up -d
mvn spring-boot:runKafka is exposed at localhost:9092; Kafka UI is at http://localhost:8081.
| Method | Endpoint | Description |
|---|---|---|
POST |
/rides/requests |
Creates and publishes one ride request |
POST |
/rides/bulk/{count} |
Publishes generated ride requests and waits for send futures |
Invoke-RestMethod -Method Post `
-Uri "http://localhost:8080/rides/requests" `
-ContentType "application/json" `
-Body '{"passengerId":"passenger-101","pickupLocation":"MSRIT","destinationLocation":"Electronic City"}'- Start and observe your first event
- Understand the system architecture
- Learn Kafka through RouteX
- Follow producers, consumers, partitions, groups, offsets, retries, and DLT recovery
- Compare RouteX with production systems
- Revise with the interview guide and cheat sheet
| Path | Focus |
|---|---|
| 01 Getting started | Local setup and first observation |
| 02 System architecture | Components, packages, and event flow |
| 03 Event-driven architecture | Why RouteX uses events |
| 04 Kafka fundamentals | Kafka concepts mapped to the code |
| 05–06 Producers and consumers | Client and listener behaviour |
| 07–14 Topic to DLT | Topology, ordering, groups, offsets, acknowledgements, retries |
| 15–16 Operations | Producer tuning and observability |
| 17–22 Reference and revision | API, production, interview, cheat sheet, FAQ |
Contributions should preserve the learning-first approach: tie claims to executable source, use RouteX before general theory, and distinguish production guidance from current implementation.
No license file is currently present. Add one before treating the repository as openly reusable.