hexagonal-architecture

Name: hexagonal-architecture
Author: rrezartprebreza

174stars33forks

How to install hexagonal-architecture?

rrezartprebreza/spring-boot-skills/hexagonal-architecture

$npx -y skills add rrezartprebreza/spring-boot-skills --skill hexagonal-architecture

Installs into the current project.

Summary

Use when the project follows hexagonal (ports & adapters) architecture. Prevents domain code from depending on Spring or JPA. Use when you see packages like domain/, application/, infrastructure/, or adapters/ in the project structure.

Files · 1

View on GitHub

SKILL.md

1	# Hexagonal Architecture
2
3	## Package Structure
4
5	```
6	src/main/java/com/example/
7	├── domain/ ← Pure Java. Zero framework dependencies.
8	│ ├── model/ ← Entities, value objects, aggregates
9	│ ├── port/
10	│ │ ├── in/ ← Use case interfaces (driving ports)
11	│ │ └── out/ ← Repository/external interfaces (driven ports)
12	│ └── service/ ← Domain services (pure business logic)
13	├── application/ ← Orchestrates use cases. Spring allowed here.
14	│ └── usecase/ ← @Service implementations of domain ports
15	└── infrastructure/ ← All framework/DB/HTTP details
16	├── persistence/ ← JPA adapters implementing out ports
17	├── web/ ← REST controllers (driving adapters)
18	└── external/ ← HTTP clients, messaging adapters
19	```
20
21	## Domain Layer — Zero Spring
22
23	```java
24	// domain/model/Order.java — pure Java, no annotations
25	public class Order {
26	private final OrderId id;
27	private final CustomerId customerId;
28	private OrderStatus status;
29	private final List<OrderItem> items;
30
31	private Order(OrderId id, CustomerId customerId) {
32	this.id = id;
33	this.customerId = customerId;
34	this.status = OrderStatus.PENDING;
35	this.items = new ArrayList<>();
36	}
37
38	public static Order create(CustomerId customerId) {
39	return new Order(OrderId.generate(), customerId);
40	}
41
42	public void addItem(ProductId productId, int quantity, Money price) {
43	if (status != OrderStatus.PENDING)
44	throw new OrderNotModifiableException(id);
45	items.add(new OrderItem(productId, quantity, price));
46	}
47
48	// Getters only — no setters
49	}
50
51	// domain/model/OrderId.java — value object
52	public record OrderId(UUID value) {
53	public static OrderId generate() { return new OrderId(UUID.randomUUID()); }
54	public static OrderId of(String value) { return new OrderId(UUID.fromString(value)); }
55	}
56	```
57
58	## Ports — Interfaces Only
59
60	```java
61	// domain/port/in/CreateOrderUseCase.java — driving port
62	public interface CreateOrderUseCase {
63	Order createOrder(CreateOrderCommand command);
64	}
65
66	// domain/port/in/CreateOrderCommand.java
67	public record CreateOrderCommand(CustomerId customerId, List<OrderItemData> items) {}
68
69	// domain/port/out/OrderRepository.java — driven port
70	public interface OrderRepository {
71	Order save(Order order);
72	Optional<Order> findById(OrderId id);
73	List<Order> findByCustomer(CustomerId customerId);
74	}
75
76	// domain/port/out/InventoryPort.java — driven port
77	public interface InventoryPort {
78	void reserve(List<OrderItem> items);
79	void release(List<OrderItem> items);
80	}
81	```
82
83	## Application Layer — Use Case Implementation
84
85	```java
86	// application/usecase/CreateOrderService.java
87	@Service // Spring allowed here
88	@RequiredArgsConstructor
89	@Transactional
90	public class CreateOrderService implements CreateOrderUseCase {
91
92	private final OrderRepository orderRepository; // domain port (not JPA repo)
93	private final InventoryPort inventoryPort; // domain port
94
95	@Override
96	public Order createOrder(CreateOrderCommand command) {
97	Order order = Order.create(command.customerId());
98	command.items().forEach(item ->
99	order.addItem(item.productId(), item.quantity(), item.price()));
100	inventoryPort.reserve(order.getItems());
101	return orderRepository.save(order);
102	}
103	}
104	```
105
106	## Infrastructure — Adapters
107
108	```java
109	// infrastructure/persistence/JpaOrderRepository.java — implements domain port
110	@Repository
111	@RequiredArgsConstructor
112	public class JpaOrderRepository implements OrderRepository {
113
114	private final SpringDataOrderRepository springDataRepo;
115	private final OrderMapper mapper;
116
117	@Override
118	public Order save(Order order) {
119	OrderJpaEntity entity = mapper.toEntity(order);
120	return mapper.toDomain(springDataRepo.save(entity));
121	}
122
123	@Override
124	public Optional<Order> findById(OrderId id) {
125	return springDataRepo.findById(id.value()).map(mapper::toDomain);
126	}
127	}
128
129	// Separate Spring Data interface — infrastructure detail
130	interface SpringDataOrderRepository extends JpaRepository<OrderJpaEntity, UUID> {}
131
132	// infrastructure/web/OrderController.java — driving adapter
133	@RestController
134	@RequestMapping("/api/v1/orders")
135	@RequiredArgsConstructor
136	public class OrderController {
137
138	private final CreateOrderUseCase createOrderUseCase; // injects use case port
139
140	@PostMapping
141	public ResponseEntity<ApiResponse<OrderResponse>> create(@Valid @RequestBody CreateOrderRequest request) {
142	Order order = createOrderUseCase.createOrder(request.toCommand());

People who liked this also viewed

6 picks

Type

hexagonal-architecture

174stars33forks

View on GitHub

How to install hexagonal-architecture?

rrezartprebreza/spring-boot-skills/hexagonal-architecture

$npx -y skills add rrezartprebreza/spring-boot-skills --skill hexagonal-architecture

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Hexagonal Architecture
2
3	## Package Structure
4
5	```
6	src/main/java/com/example/
7	├── domain/ ← Pure Java. Zero framework dependencies.
8	│ ├── model/ ← Entities, value objects, aggregates
9	│ ├── port/
10	│ │ ├── in/ ← Use case interfaces (driving ports)
11	│ │ └── out/ ← Repository/external interfaces (driven ports)
12	│ └── service/ ← Domain services (pure business logic)
13	├── application/ ← Orchestrates use cases. Spring allowed here.
14	│ └── usecase/ ← @Service implementations of domain ports
15	└── infrastructure/ ← All framework/DB/HTTP details
16	├── persistence/ ← JPA adapters implementing out ports
17	├── web/ ← REST controllers (driving adapters)
18	└── external/ ← HTTP clients, messaging adapters
19	```
20
21	## Domain Layer — Zero Spring
22
23	```java
24	// domain/model/Order.java — pure Java, no annotations
25	public class Order {
26	private final OrderId id;
27	private final CustomerId customerId;
28	private OrderStatus status;
29	private final List<OrderItem> items;
30
31	private Order(OrderId id, CustomerId customerId) {
32	this.id = id;
33	this.customerId = customerId;
34	this.status = OrderStatus.PENDING;
35	this.items = new ArrayList<>();
36	}
37
38	public static Order create(CustomerId customerId) {
39	return new Order(OrderId.generate(), customerId);
40	}
41
42	public void addItem(ProductId productId, int quantity, Money price) {
43	if (status != OrderStatus.PENDING)
44	throw new OrderNotModifiableException(id);
45	items.add(new OrderItem(productId, quantity, price));
46	}
47
48	// Getters only — no setters
49	}
50
51	// domain/model/OrderId.java — value object
52	public record OrderId(UUID value) {
53	public static OrderId generate() { return new OrderId(UUID.randomUUID()); }
54	public static OrderId of(String value) { return new OrderId(UUID.fromString(value)); }
55	}
56	```
57
58	## Ports — Interfaces Only
59
60	```java
61	// domain/port/in/CreateOrderUseCase.java — driving port
62	public interface CreateOrderUseCase {
63	Order createOrder(CreateOrderCommand command);
64	}
65
66	// domain/port/in/CreateOrderCommand.java
67	public record CreateOrderCommand(CustomerId customerId, List<OrderItemData> items) {}
68
69	// domain/port/out/OrderRepository.java — driven port
70	public interface OrderRepository {
71	Order save(Order order);
72	Optional<Order> findById(OrderId id);
73	List<Order> findByCustomer(CustomerId customerId);
74	}
75
76	// domain/port/out/InventoryPort.java — driven port
77	public interface InventoryPort {
78	void reserve(List<OrderItem> items);
79	void release(List<OrderItem> items);
80	}
81	```
82
83	## Application Layer — Use Case Implementation
84
85	```java
86	// application/usecase/CreateOrderService.java
87	@Service // Spring allowed here
88	@RequiredArgsConstructor
89	@Transactional
90	public class CreateOrderService implements CreateOrderUseCase {
91
92	private final OrderRepository orderRepository; // domain port (not JPA repo)
93	private final InventoryPort inventoryPort; // domain port
94
95	@Override
96	public Order createOrder(CreateOrderCommand command) {
97	Order order = Order.create(command.customerId());
98	command.items().forEach(item ->
99	order.addItem(item.productId(), item.quantity(), item.price()));
100	inventoryPort.reserve(order.getItems());
101	return orderRepository.save(order);
102	}
103	}
104	```
105
106	## Infrastructure — Adapters
107
108	```java
109	// infrastructure/persistence/JpaOrderRepository.java — implements domain port
110	@Repository
111	@RequiredArgsConstructor
112	public class JpaOrderRepository implements OrderRepository {
113
114	private final SpringDataOrderRepository springDataRepo;
115	private final OrderMapper mapper;
116
117	@Override
118	public Order save(Order order) {
119	OrderJpaEntity entity = mapper.toEntity(order);
120	return mapper.toDomain(springDataRepo.save(entity));
121	}
122
123	@Override
124	public Optional<Order> findById(OrderId id) {
125	return springDataRepo.findById(id.value()).map(mapper::toDomain);
126	}
127	}
128
129	// Separate Spring Data interface — infrastructure detail
130	interface SpringDataOrderRepository extends JpaRepository<OrderJpaEntity, UUID> {}
131
132	// infrastructure/web/OrderController.java — driving adapter
133	@RestController
134	@RequestMapping("/api/v1/orders")
135	@RequiredArgsConstructor
136	public class OrderController {
137
138	private final CreateOrderUseCase createOrderUseCase; // injects use case port
139
140	@PostMapping
141	public ResponseEntity<ApiResponse<OrderResponse>> create(@Valid @RequestBody CreateOrderRequest request) {
142	Order order = createOrderUseCase.createOrder(request.toCommand());

People who liked this also viewed

6 picks

Type