Hexagonal Architecture

// ❌ BAD — infrastructure leaks into domain, anemic model, no ports

@Service
@RequiredArgsConstructor
public class CreateOrderService {

    private final OrderJpaRepository orderRepository;     // JPA repo directly — no domain port
    private final RestTemplate restTemplate;               // infrastructure in application layer

    @Transactional
    public OrderEntity createOrder(CreateOrderRequest request) {
        // Business logic in service, not domain model (anemic)
        if (request.getItems().isEmpty()) {
            throw new RuntimeException("No items");       // generic exception, no domain meaning
        }

        OrderEntity order = new OrderEntity();            // JPA entity used as domain model
        order.setCustomerEmail(request.getEmail());       // setter-based, no invariant enforcement
        order.setStatus("PENDING");                       // string instead of enum/value object

        for (ItemRequest item : request.getItems()) {
            OrderItemEntity orderItem = new OrderItemEntity();  // direct child construction
            orderItem.setProductId(item.getProductId());
            orderItem.setQuantity(item.getQuantity());
            order.getItems().add(orderItem);              // bypasses aggregate root
        }

        // Infrastructure call mixed with business logic
        restTemplate.postForEntity(                       // HTTP call in service, not behind port
            "http://inventory-service/reserve",
            request.getItems(), Void.class);

        return orderRepository.save(order);               // returns JPA entity, not domain model
    }
}

// Domain model polluted with JPA
@Entity                                                   // JPA annotation in domain model
@Data                                                     // generates setters — no encapsulation
public class OrderEntity {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;                                      // Long ID, not typed value object
    private String customerEmail;
    private String status;                                // String instead of OrderStatus enum
    @OneToMany private List<OrderItemEntity> items;       // missing cascade, orphanRemoval
}

// ✅ GOOD — use case implements port, injects domain ports, no Spring annotations in domain

// --- Domain port (in domain layer, no Spring imports) ---
public interface CreateOrderUseCase {
    Order execute(CreateOrderCommand command);
}

public interface OrderRepository {  // domain port — not Spring's JpaRepository
    Order save(Order order);
    Optional<Order> findById(OrderId id);
}

// --- Application layer (implements use case, orchestrates domain) ---
@Service
@RequiredArgsConstructor
@Transactional
public class CreateOrderService implements CreateOrderUseCase {

    private final OrderRepository orderRepository;        // domain port, not JPA
    private final InventoryPort inventoryPort;             // domain port for external system

    @Override
    public Order execute(CreateOrderCommand command) {
        inventoryPort.reserve(command.items());
        Order order = Order.create(command.customerEmail(), command.items());
        return orderRepository.save(order);
    }
}

// --- Domain model (no JPA annotations, pure business logic) ---
public class Order {
    private final OrderId id;
    private final EmailAddress customerEmail;
    private OrderStatus status;
    private final List<OrderItem> items;

    public static Order create(EmailAddress email, List<OrderItemCommand> items) {
        Order order = new Order(OrderId.generate(), email, OrderStatus.PENDING, new ArrayList<>());
        items.forEach(i -> order.addItem(i.productId(), i.quantity()));
        return order;
    }

    public void addItem(ProductId productId, int quantity) {
        if (status != OrderStatus.PENDING)
            throw new OrderNotModifiableException(id);
        items.add(new OrderItem(productId, quantity));
    }
}

package com.example.order.infrastructure.persistence;

import com.example.order.domain.model.Order;
import com.example.order.domain.model.OrderId;
import com.example.order.domain.port.out.OrderRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;

import java.util.Optional;

/**
 * Persistence adapter — implements domain port using JPA.
 * Domain layer never sees JPA, only this adapter does.
 */
@Component
@RequiredArgsConstructor
public class OrderJpaAdapter implements OrderRepository {

    private final SpringDataOrderRepository jpaRepository;
    private final OrderPersistenceMapper mapper;

    @Override
    public Order save(Order order) {
        OrderJpaEntity entity = mapper.toJpaEntity(order);
        OrderJpaEntity saved = jpaRepository.save(entity);
        return mapper.toDomainModel(saved);
    }

    @Override
    public Optional<Order> findById(OrderId id) {
        return jpaRepository.findById(id.value())
            .map(mapper::toDomainModel);
    }

    @Override
    public void deleteById(OrderId id) {
        jpaRepository.deleteById(id.value());
    }
}

/**
 * Spring Data JPA repository — internal to infrastructure layer.
 * Never exposed outside this package.
 */
interface SpringDataOrderRepository extends org.springframework.data.jpa.repository.JpaRepository<OrderJpaEntity, java.util.UUID> {
}

package com.example.order.infrastructure.persistence;

import jakarta.persistence.*;
import lombok.AccessLevel;
import lombok.Getter;
import lombok.NoArgsConstructor;
import org.hibernate.annotations.CreationTimestamp;
import org.hibernate.annotations.UpdateTimestamp;

import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

/**
 * JPA entity — lives in infrastructure layer, separate from domain model.
 * Maps between database schema and persistence. Never used in domain logic.
 */
@Entity
@Table(name = "orders")
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class OrderJpaEntity {

    @Id
    @Column(updatable = false, nullable = false)
    private UUID id;

    @Column(name = "customer_email", nullable = false)
    private String customerEmail;

    // Stored as the enum's name; the persistence mapper converts to/from OrderStatus.
    // (@Enumerated only applies to enum-typed fields — on a String Hibernate fails at startup.)
    @Column(nullable = false)
    private String status;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItemJpaEntity> items = new ArrayList<>();

    @CreationTimestamp
    @Column(updatable = false)
    private Instant createdAt;

    @UpdateTimestamp
    private Instant updatedAt;

    @Version
    private Long version;

    // Used by mapper only — no public constructor
    OrderJpaEntity(UUID id, String customerEmail, String status) {
        this.id = id;
        this.customerEmail = customerEmail;
        this.status = status;
    }

    void addItem(OrderItemJpaEntity item) {
        items.add(item);
        item.setOrder(this);
    }
}