rrezartprebreza/spring-boot-skills / skills/spring-boot-3/hexagonal-architecture
hexagonal-architecture
VerifiedUse 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.
Hexagonal Architecture
Package Structure
src/main/java/com/example/
├── domain/ ← Pure Java. Zero framework dependencies.
│ ├── model/ ← Entities, value objects, aggregates
│ ├── port/
│ │ ├── in/ ← Use case interfaces (driving ports)
│ │ └── out/ ← Repository/external interfaces (driven ports)
│ └── service/ ← Domain services (pure business logic)
├── application/ ← Orchestrates use cases. Spring allowed here.
│ └── usecase/ ← @Service implementations of domain ports
└── infrastructure/ ← All framework/DB/HTTP details
├── persistence/ ← JPA adapters implementing out ports
├── web/ ← REST controllers (driving adapters)
└── external/ ← HTTP clients, messaging adapters
Domain Layer — Zero Spring
// domain/model/Order.java — pure Java, no annotations
public class Order {
private final OrderId id;
private final CustomerId customerId;
private OrderStatus status;
private final List<OrderItem> items;
private Order(OrderId id, CustomerId customerId) {
this.id = id;
this.customerId = customerId;
this.status = OrderStatus.PENDING;
this.items = new ArrayList<>();
}
public static Order create(CustomerId customerId) {
return new Order(OrderId.generate(), customerId);
}
public void addItem(ProductId productId, int quantity, Money price) {
if (status != OrderStatus.PENDING)
throw new OrderNotModifiableException(id);
items.add(new OrderItem(productId, quantity, price));
}
// Getters only — no setters
}
// domain/model/OrderId.java — value object
public record OrderId(UUID value) {
public static OrderId generate() { return new OrderId(UUID.randomUUID()); }
public static OrderId of(String value) { return new OrderId(UUID.fromString(value)); }
}
Ports — Interfaces Only
// domain/port/in/CreateOrderUseCase.java — driving port
public interface CreateOrderUseCase {
Order createOrder(CreateOrderCommand command);
}
// domain/port/in/CreateOrderCommand.java
public record CreateOrderCommand(CustomerId customerId, List<OrderItemData> items) {}
// domain/port/out/OrderRepository.java — driven port
public interface OrderRepository {
Order save(Order order);
Optional<Order> findById(OrderId id);
void deleteById(OrderId id);
}
// domain/port/out/InventoryPort.java — driven port
public interface InventoryPort {
void reserve(List<OrderItem> items);
void release(List<OrderItem> items);
}
Application Layer — Use Case Implementation
// application/usecase/CreateOrderService.java
@Service // Spring allowed here
@RequiredArgsConstructor
@Transactional
public class CreateOrderService implements CreateOrderUseCase {
private final OrderRepository orderRepository; // domain port (not JPA repo)
private final InventoryPort inventoryPort; // domain port
@Override
public Order createOrder(CreateOrderCommand command) {
Order order = Order.create(command.customerId());
command.items().forEach(item ->
order.addItem(item.productId(), item.quantity(), item.price()));
inventoryPort.reserve(order.getItems());
return orderRepository.save(order);
}
}
Infrastructure — Adapters
// infrastructure/persistence/JpaOrderRepository.java — implements domain port
@Repository
@RequiredArgsConstructor
public class JpaOrderRepository implements OrderRepository {
private final SpringDataOrderRepository springDataRepo;
private final OrderMapper mapper;
@Override
public Order save(Order order) {
OrderJpaEntity entity = mapper.toEntity(order);
return mapper.toDomain(springDataRepo.save(entity));
}
@Override
public Optional<Order> findById(OrderId id) {
return springDataRepo.findById(id.value()).map(mapper::toDomain);
}
@Override
public void deleteById(OrderId id) {
springDataRepo.deleteById(id.value());
}
}
// Separate Spring Data interface — infrastructure detail
interface SpringDataOrderRepository extends JpaRepository<OrderJpaEntity, UUID> {}
// infrastructure/web/OrderController.java — driving adapter
@RestController
@RequestMapping("/api/v1/orders")
@RequiredArgsConstructor
public class OrderController {
private final CreateOrderUseCase createOrderUseCase; // injects use case port
@PostMapping
public ResponseEntity<ApiResponse<OrderResponse>> create(@Valid @RequestBody CreateOrderRequest request) {
Order order = createOrderUseCase.createOrder(request.toCommand());
return ResponseEntity.status(201).body(ApiResponse.ok(OrderResponse.from(order)));
}
}
Gotchas
- Agent imports
javax.persistencein domain classes — domain must be framework-free - Agent injects
JpaRepositorydirectly into use cases — use domain port interfaces - Agent puts
@Transactionalon domain services — belongs in application layer - Agent mixes driving and driven ports —
port/in= what app offers,port/out= what app needs - Agent creates anemic domain with only getters/setters — behavior belongs on domain objects
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |