hexagonal-architecture-layers-java

Hexagonal architecture layering for Java services with strict boundaries. Trigger: When structuring Java apps by Domain/Application/Infrastructure, or refactoring toward clean architecture.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

When to Use

Load this skill when:

Designing a new Java service with clean, testable layers
Refactoring Spring code to isolate the domain from frameworks
Supporting multiple adapters (REST + messaging, JPA + Mongo)
Enforcing dependency direction and clear module boundaries

Critical Patterns

Pattern 1: Domain is pure

Domain has no framework annotations, no persistence concerns, and no I/O.

Pattern 2: Application orchestrates

Application defines use cases and ports, calling domain logic and delegating I/O to ports.

Pattern 3: Infrastructure adapts

Infrastructure implements ports and wires adapters (controllers, repositories, clients).

Code Examples

Example 1: Domain model + output port

package com.acme.order.domain;

public record OrderId(String value) { }

public final class Order {
  private final OrderId id;
  private final Money total;

  public Order(OrderId id, Money total) {
    this.id = id;
    this.total = total;
  }

  public OrderId id() { return id; }
  public Money total() { return total; }
}

package com.acme.order.application.port;

import com.acme.order.domain.Order;
import com.acme.order.domain.OrderId;

public interface OrderRepositoryPort {
  OrderId nextId();
  void save(Order order);
}

Example 2: Application use case + input port

package com.acme.order.application.usecase;

import com.acme.order.application.port.OrderRepositoryPort;
import com.acme.order.domain.Order;
import com.acme.order.domain.OrderId;
import com.acme.order.domain.Money;

public interface PlaceOrderUseCase {
  OrderId place(Money total);
}

public final class PlaceOrderService implements PlaceOrderUseCase {
  private final OrderRepositoryPort repository;

  public PlaceOrderService(OrderRepositoryPort repository) {
    this.repository = repository;
  }

  @Override
  public OrderId place(Money total) {
    OrderId id = repository.nextId();
    Order order = new Order(id, total);
    repository.save(order);
    return id;
  }
}

Example 3: Infrastructure adapter + wiring

package com.acme.order.infrastructure.persistence;

import com.acme.order.application.port.OrderRepositoryPort;
import com.acme.order.domain.Order;
import com.acme.order.domain.OrderId;
import org.springframework.stereotype.Repository;

@Repository
public final class OrderJpaAdapter implements OrderRepositoryPort {
  private final SpringOrderRepository repository;
  private final OrderMapper mapper;

  public OrderJpaAdapter(SpringOrderRepository repository, OrderMapper mapper) {
    this.repository = repository;
    this.mapper = mapper;
  }

  @Override
  public OrderId nextId() {
    return new OrderId(java.util.UUID.randomUUID().toString());
  }

  @Override
  public void save(Order order) {
    repository.save(mapper.toEntity(order));
  }
}

Anti-Patterns

Don't: Put framework annotations in domain

// BAD: domain tied to JPA
@jakarta.persistence.Entity
public class Order {
  @jakarta.persistence.Id
  private String id;
}

Don't: Call infrastructure directly from domain

// BAD: domain depends on Spring repository
public class Order {
  private final SpringOrderRepository repository;
}

Quick Reference

Task	Pattern
Persist domain data	Define output port in application, implement in infrastructure
Expose use case	Define input port and service in application
Keep domain pure	No annotations, no I/O, no framework imports

Resources

Hexagonal Architecture: https://alistair.cockburn.us/hexagonal-architecture/
Clean Architecture: https://www.oreilly.com/library/view/clean-architecture/9780134494272/

Repository: Gentleman-Programming/Gentleman-Skills
Path: community/hexagonal-architecture-layers-java/SKILL.md
Commit: c8036a3

Last updated: 5 days ago
First committed: 8 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.