https://github.com/hirannor/oms-hexagonal-architecture-ddd
An Order Management System with Spring Boot example implementing Ports & Adapters / Hexagonal Architecture with Domain-Driven Design (DDD) principles.
https://github.com/hirannor/oms-hexagonal-architecture-ddd
architecture clean-architecture ddd ddd-patterns event-driven eventbus hexagonal-architecture java jdk21 messaging messaging-queue port-and-adapters rabbitmq rest software-architecture software-development spring-boot spring-data-jpa springframework
Last synced: 26 days ago
JSON representation
An Order Management System with Spring Boot example implementing Ports & Adapters / Hexagonal Architecture with Domain-Driven Design (DDD) principles.
- Host: GitHub
- URL: https://github.com/hirannor/oms-hexagonal-architecture-ddd
- Owner: hirannor
- License: other
- Created: 2023-04-16T19:01:36.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-10-05T11:26:29.000Z (8 months ago)
- Last Synced: 2025-10-05T13:19:28.762Z (8 months ago)
- Topics: architecture, clean-architecture, ddd, ddd-patterns, event-driven, eventbus, hexagonal-architecture, java, jdk21, messaging, messaging-queue, port-and-adapters, rabbitmq, rest, software-architecture, software-development, spring-boot, spring-data-jpa, springframework
- Language: Java
- Homepage:
- Size: 820 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 🧩 Order Management System (OMS)
| CI Status | License |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [](https://github.com/hirannor/oms-hexagonal-architecture-ddd/actions/workflows/ci.yml) | [](https://opensource.org/licenses/MIT) [](https://commonsclause.com/) |
---
## 🧭 Overview
The **Order Management System (OMS)** is a **full-stack demo project** that showcases
modern enterprise application design using **Hexagonal Architecture**, **Domain-Driven Design (DDD)**,
and **event-driven communication** between bounded contexts.
### Tech Highlights
- **Backend:** Spring Boot 3 · Java 21 · Hexagonal Architecture · DDD · RabbitMQ · PostgreSQL
- **Frontend:** Angular 20 (Nx Monorepo + NgRx) · PrimeNG · TypeScript
- **API Contract:** Centralized [OpenAPI 3.0.3](openapi/) definitions shared between backend & frontend
> 📘 For in-depth domain and architecture documentation:
>
> - **Backend:** [oms-backend/README.md](oms-backend/README.md) — Spring Boot + DDD + Hexagonal Architecture
> - **Frontend:** [oms-frontend/README.md](oms-frontend/README.md) — Angular 20 + Nx + NgRx Modular Monorepo
## ⚙️ Architecture Overview
### Backend — Hexagonal (Ports & Adapters)
| Layer | Responsibility |
|:----------------|:---------------------------------------------------------------------|
| **Domain** | Core business logic, aggregates, and domain events. |
| **Application** | Use-case orchestration and coordination between domain and adapters. |
| **Adapters** | Persistence, messaging, web, and external system integrations. |
The architecture enforces clear separation through **ArchUnit** tests and follows a strict dependency flow:
### Frontend — Nx Modular Architecture
The Angular workspace mirrors backend bounded contexts and enforces clear separation of concerns:
- `libs//-feature` → **Feature-specific UI modules**
Contain routed feature shells, smart/presentational components, and domain-focused UI implementations.
**e.g.** `libs/product/product-feature`
- `libs//-data-access` → **State management and domain data layer**
Encapsulates NgRx store, actions, reducers, selectors, effects, facades, and a service layer.
Effects use the service layer, which wraps the generated OpenAPI client and maps API responses into domain models.
**e.g.** `libs/product/product-data-access`
- `libs/openapi/-data-access` → **Generated OpenAPI clients for backend APIs**
Auto-generated TypeScript clients containing raw API methods and models (no business logic).
**e.g.** `libs/openapi/product-data-access`
- `libs/shared` → **Reusable shared infrastructure and UI**
Provides cross-cutting components, interceptors, guards, layout, and common utilities.
- `libs/models` → **Core domain model definitions**
Contains type-safe interfaces and value objects shared across all frontend libraries.
## 🧩 Domain Model
| Aggregate | Responsibility |
|---------------|--------------------------------------------------------------------------------------------------------------------------|
| **Customer** | Represents a system user; handles registration, authentication, and profile management. |
| **Order** | Full order lifecycle (creation → payment → shipment → delivery → refund); emits events like `OrderCreated`, `OrderPaid`. |
| **Basket** | Shopping cart per customer; add/remove products and initiate checkout. |
| **Product** | Catalog item with immutable attributes (id, name, price, currency). |
| **Inventory** | Tracks stock; supports `reserve`, `release`, `deduct`; prevents overselling. |
| **Payment** | Lifecycle via Stripe (`INITIALIZED → SUCCEEDED/FAILED/CANCELED`); emits events like `PaymentSucceeded`. |
All aggregates emit **domain events**, which are persisted and published asynchronously for eventual consistency.
---
## 📡 Messaging & Event Flow
The backend leverages an **Outbox Pattern + RabbitMQ** setup for guaranteed, reliable delivery:
1. Domain events are persisted in the **Outbox** table (same transaction).
2. A scheduled job publishes messages from Outbox → RabbitMQ exchange.
3. Rabbit listeners consume messages and re-emit them as in-app events.
This ensures **exactly-once semantics** and stable inter-module communication.
---
## 🌐 Frontend (Angular + Nx + NgRx)
### Key Concepts
- Modular feature libraries for each domain (`auth`, `basket`, `order`, `product`, etc.)
- Typed REST clients generated from `/openapi` using:
```bash
npm run generate:apis
