salahuddin09/hexagonal-kafka-outbox

1. This is a Spring Boot hexagonal application centered on an order-processing workflow. The core runtime is Java 25 with Spring Web MVC, Spring Data JPA, Spring Validation, Spring Mail, Flyway, and Apache Kafka. The main infrastructure dependencies are PostgreSQL for state, Kafka for async events, and SMTP/Mailpit for email delivery.

2. The inbound HTTP boundary is under adapter.in.web. It exposes REST controllers for users, products, orders, and outbox events. OrderController is the primary write entrypoint and returns 202 Accepted for order creation, emphasizing asynchronous processing rather than immediate completion.

3. The application layer under application defines the use-case ports and orchestration services. CreateOrderService, ListOrdersService, ListUsersService, ListProductsService, and ListOutboxEventsService are the main application services. Ports split the direction of dependency: inbound use cases (CreateOrderUseCase, etc.) and outbound persistence/messaging contracts (OrderPersistencePort, OutboxEventPort, EmailSenderPort, and query ports for users/products).

4. The domain layer under domain contains the business model and enums. Key aggregates and events include Order, OrderItem, User, Product, OutboxEvent, OrderCreatedEvent, and invoice-related models such as InvoiceEmail and InvoiceEmailOutboxPayload. Status enums like OrderStatus and OutboxStatus drive lifecycle transitions.

5. Persistence is isolated in adapter.out.persistence. It maps domain objects to JPA entities such as OrderJpaEntity, OrderItemJpaEntity, UserJpaEntity, ProductJpaEntity, OutboxEventJpaEntity, and InvoiceEmailJpaEntity, with Spring Data repositories behind them. PersistenceMapper and the adapter classes translate between domain and database shapes, while Flyway migrations define the schema in src/main/resources/db/migration.

6. The key reliability mechanism is the outbox table. When an order is created, the application stores the order and an ORDER_CREATED record in outbox_events within the same transaction. That table also holds retry metadata such as attempt count, status, error message, and timestamps, which makes downstream publishing retryable and observable.

7. adapter.out.messaging contains the asynchronous delivery side. OutboxPublisher is the scheduled poller that reads pending outbox rows and dispatches them through type-specific publishers. For order events it uses KafkaOrderEventPublisher; for invoice-email events it uses EmailInvoiceOutboxDispatcher and SmtpInvoiceEmailSender.

8. Kafka is used as the first async hop after order creation. OrderCreatedInvoiceConsumer in adapter.in.messaging consumes the order-created topic and kicks off invoice-email generation. This consumer bridges the Kafka event back into an application use case (CreateInvoiceEmailFromOrderCreatedEventService) rather than handling business logic directly.

9. The invoice-email flow is a second outbox-backed stage. The consumer builds invoice content using helpers like LoadOrderUserService, LoadOrderProductsService, and InvoiceEmailBodyFactory, persists an invoice_emails record, and emits an EMAIL_INVOICE_REQUESTED outbox event. That event is later picked up by OutboxPublisher, sent via SMTP, and the order can move to INVOICE_DELIVERED.

10. Configuration is centralized in config. KafkaProducerConfiguration, MailConfiguration, AsyncConfiguration, ModelMapperConfiguration, and OpenApiConfiguration wire the infrastructure. Runtime behavior can be toggled with flags such as enabling the invoice consumer or the outbox publisher, which is important for diagramming optional async subsystems.

11. The project also has a small bootstrap/data-seeding concern in DataFixtureConfiguration, which inserts default user/product rows only when the tables are empty. That means the application can start with usable catalog data without depending on manual setup.

12. Operationally, the app exposes Swagger/OpenAPI and Actuator health endpoints, but the architectural observability focus is Kafka UI for topic inspection and Mailpit for captured emails. The test suite uses Testcontainers against PostgreSQL and Kafka, so the integration boundary is intentionally exercised against real infrastructure rather than mocks.