Order Events Service Spring Boot event-driven microservice

Portfolio backend project

Order Events Service

A focused Spring Boot service that persists orders, publishes Kafka events, consumes them idempotently, and exposes generated API and coverage documentation through GitHub Pages.

User guide API documentation Coverage report

System Overview

The service exposes one business workflow: validate and persist an order, publish an OrderCreatedEvent, consume it, and atomically claim its event ID. The project stays deliberately focused on this reliability path.

REST API

Validates create-order requests and returns a stable response contract.

PostgreSQL

Stores orders and the consumer idempotency table managed by Flyway.

Kafka

Publishes and consumes order.created.v1 events with DLT recovery.

Architecture

The main delivery path and its persistence, idempotency, and failure branches are shown separately to reflect the implementation.

  1. Client
  2. REST API
  3. Order Service
  4. Kafka Producer
  5. order.created.v1
  6. Kafka Consumer
Order persistenceOrder Service to PostgreSQL
IdempotencyKafka Consumer to processed_events
Failure pathKafka Consumer to retry, then order.created.v1.dlt

Quality and Reliability

Idempotency

PostgreSQL atomically inserts each eventId. A conflict means the delivery is already complete and becomes a successful no-op.

Retry and DLT

Listener failures propagate to Spring Kafka retry and then to order.created.v1.dlt after attempts are exhausted.

Build gates

Maven verification runs behavior tests, exports OpenAPI, generates JaCoCo, and assembles the Pages artifact.

Documentation

GitHub Pages publishes only Maven-generated output from target/pages.

User guideHTML guide generated from docs/user-guide.md during Maven verification. API documentationStatic OpenAPI HTML generated from the exported spec. OpenAPI JSONRaw specification published with the generated documentation. JaCoCo reportCoverage report generated at target/site/jacoco/index.html. READMEProject entry point, architecture, and design trade-offs. RepositorySource code and GitHub Actions workflow.

CI/CD

Pull requests

Run ./mvnw clean verify, validate generated artifacts and Compose, and build the Docker image.

Main branch

Uploads target/pages with the official GitHub Pages actions and deploys it.

Repository hygiene

Build output, generated sources, reports, local logs, and Docker temporary files stay untracked.

Intentional Scope

Focused reliability

Kafka publication, idempotent consumption, retry handling, DLT routing, and PostgreSQL persistence are the core design surface.

Generated quality signals

OpenAPI documentation, Docker-based local development, CI checks, and JaCoCo reports are produced by the build.

Deliberate exclusions

Transactional outbox, schema registry, distributed tracing, Kubernetes, saga orchestration, and additional microservices are out of scope.