clean architecture

// Domain Entity — pure Java, NO Spring annotations, NO JPA annotations
public class Order {
   private final OrderId id;
   private final CustomerId customerId;
   private final List<OrderItem> items;
   private OrderStatus status;
   private Money totalAmount;
   private LocalDateTime createdAt;
 
   // Business rules LIVE HERE
   public void confirm() {
       if (this.status != OrderStatus.PENDING) {
           throw new IllegalOrderStateException(
               "Cannot confirm order in status: " + this.status);
       }
       if (this.items.isEmpty()) {
           throw new EmptyOrderException("Order must have at least 1 item");
       }
       this.status = OrderStatus.CONFIRMED;
   }
 
   public void cancel(String reason) {
       if (this.status == OrderStatus.SHIPPED) {
           throw new IllegalOrderStateException("Cannot cancel shipped order");
       }
       this.status = OrderStatus.CANCELLED;
   }
 
   public Money calculateTotal() {
       return items.stream()
           .map(item -> item.getPrice().multiply(item.getQuantity()))
           .reduce(Money.ZERO, Money::add);
   }
 
   // No setters — state changes only through business methods
}
 
// Value Object — immutable, equality by value
public record Money(BigDecimal amount, String currency) {
   public static final Money ZERO = new Money(BigDecimal.ZERO, "VND");
 
   public Money {
       if (amount.compareTo(BigDecimal.ZERO) < 0)
           throw new IllegalArgumentException("Amount cannot be negative");
   }
 
   public Money add(Money other) {
       if (!this.currency.equals(other.currency))
           throw new CurrencyMismatchException(this.currency, other.currency);
       return new Money(this.amount.add(other.amount), this.currency);
   }
 
   public Money multiply(int quantity) {
       return new Money(this.amount.multiply(BigDecimal.valueOf(quantity)), this.currency);
   }
}

// Inbound Port: Use Case interface
public interface CreateOrderUseCase {
   OrderId execute(CreateOrderCommand command);
}
 
// Command object (input to use case)
public record CreateOrderCommand(
   CustomerId customerId,
   List<OrderItemCommand> items,
   PaymentMethod paymentMethod
) {}
 
// Outbound Port: persistence
public interface OrderRepository {
   Order save(Order order);
   Optional<Order> findById(OrderId id);
   List<Order> findByCustomerId(CustomerId customerId);
}
 
// Outbound Port: external service
public interface PaymentGateway {
   PaymentResult charge(OrderId orderId, Money amount, PaymentMethod method);
   void refund(OrderId orderId);
}
 
public interface NotificationPort {
   void sendOrderConfirmation(CustomerId customerId, OrderId orderId);
}

// Use Case: orchestrate domain objects + ports
// NO Spring annotations here (optional: can add @Service for convenience)
public class CreateOrderService implements CreateOrderUseCase {
 
   private final OrderRepository orderRepository;
   private final PaymentGateway paymentGateway;
   private final InventoryGateway inventoryGateway;
   private final NotificationPort notificationPort;
 
   public CreateOrderService(OrderRepository orderRepository,
                             PaymentGateway paymentGateway,
                             InventoryGateway inventoryGateway,
                             NotificationPort notificationPort) {
       this.orderRepository = orderRepository;
       this.paymentGateway = paymentGateway;
       this.inventoryGateway = inventoryGateway;
       this.notificationPort = notificationPort;
   }
 
   @Override
   public OrderId execute(CreateOrderCommand command) {
       // 1. Create domain object (business rules validated in constructor)
       Order order = Order.create(command.customerId(), command.items());
 
       // 2. Check inventory (through port — doesn't know HOW it's checked)
       inventoryGateway.checkAvailability(order.getItems());
 
       // 3. Charge payment (through port — doesn't know it's Stripe/VnPay)
       PaymentResult payment = paymentGateway.charge(
           order.getId(), order.calculateTotal(), command.paymentMethod());
 
       if (!payment.isSuccess()) {
           throw new PaymentFailedException(payment.getErrorMessage());
       }
 
       // 4. Confirm order (domain business rule)
       order.confirm();
 
       // 5. Persist (through port — doesn't know it's PostgreSQL/MongoDB)
       orderRepository.save(order);
 
       // 6. Notify (through port — doesn't know it's email/push/SMS)
       notificationPort.sendOrderConfirmation(command.customerId(), order.getId());
 
       return order.getId();
   }
}

// Inbound Adapter: REST Controller
@RestController
@RequestMapping("/api/v1/orders")
@RequiredArgsConstructor
public class OrderController {
 
   private final CreateOrderUseCase createOrderUseCase;  // Depend on PORT, not implementation
   private final GetOrderUseCase getOrderUseCase;
 
   @PostMapping
   @ResponseStatus(HttpStatus.CREATED)
   public OrderResponse create(@Valid @RequestBody CreateOrderRequest request) {
       // Convert web DTO → domain command
       CreateOrderCommand command = new CreateOrderCommand(
           new CustomerId(request.getCustomerId()),
           request.getItems().stream().map(this::toItemCommand).toList(),
           request.getPaymentMethod()
       );
 
       // Call use case (doesn't know about HTTP, JSON, Spring)
       OrderId orderId = createOrderUseCase.execute(command);
 
       // Convert domain result → web response
       return new OrderResponse(orderId.value(), "Order created successfully");
   }
}
 
// Outbound Adapter: JPA persistence
@Component
@RequiredArgsConstructor
public class OrderPersistenceAdapter implements OrderRepository {
 
   private final OrderJpaRepository jpaRepository;  // Spring Data
   private final OrderMapper mapper;                // Domain ↔ JPA entity
 
   @Override
   public Order save(Order order) {
       OrderJpaEntity entity = mapper.toJpaEntity(order);
       OrderJpaEntity saved = jpaRepository.save(entity);
       return mapper.toDomain(saved);
   }
 
   @Override
   public Optional<Order> findById(OrderId id) {
       return jpaRepository.findById(id.value())
           .map(mapper::toDomain);
   }
}
 
// Outbound Adapter: Payment gateway (Stripe)
@Component
@RequiredArgsConstructor
public class StripePaymentAdapter implements PaymentGateway {
 
   private final StripeClient stripeClient;
 
   @Override
   public PaymentResult charge(OrderId orderId, Money amount, PaymentMethod method) {
       StripeChargeRequest stripeRequest = StripeChargeRequest.builder()
           .amount(amount.amount().movePointRight(2).longValue())  // cents
           .currency(amount.currency().toLowerCase())
           .idempotencyKey(orderId.value().toString())
           .build();
 
       StripeChargeResponse response = stripeClient.createCharge(stripeRequest);
       return new PaymentResult(response.isSucceeded(), response.getErrorMessage());
   }
}

@Configuration
public class OrderBeanConfig {
 
   @Bean
   public CreateOrderUseCase createOrderUseCase(
           OrderRepository orderRepository,
           PaymentGateway paymentGateway,
           InventoryGateway inventoryGateway,
           NotificationPort notificationPort) {
       return new CreateOrderService(
           orderRepository, paymentGateway, inventoryGateway, notificationPort);
   }
}

// Unit test Use Case — mock ports, test business logic
class CreateOrderServiceTest {
 
   private final OrderRepository orderRepository = mock(OrderRepository.class);
   private final PaymentGateway paymentGateway = mock(PaymentGateway.class);
   private final InventoryGateway inventoryGateway = mock(InventoryGateway.class);
   private final NotificationPort notificationPort = mock(NotificationPort.class);
 
   private final CreateOrderUseCase useCase = new CreateOrderService(
       orderRepository, paymentGateway, inventoryGateway, notificationPort);
 
   @Test
   void createOrder_success() {
       when(paymentGateway.charge(any(), any(), any()))
           .thenReturn(PaymentResult.success());
       when(orderRepository.save(any())).thenAnswer(i -> i.getArgument(0));
 
       OrderId result = useCase.execute(validCommand());
 
       assertThat(result).isNotNull();
       verify(orderRepository).save(argThat(order ->
           order.getStatus() == OrderStatus.CONFIRMED));
       verify(notificationPort).sendOrderConfirmation(any(), any());
   }
 
   @Test
   void createOrder_paymentFailed_throwsException() {
       when(paymentGateway.charge(any(), any(), any()))
           .thenReturn(PaymentResult.failed("Insufficient funds"));
 
       assertThatThrownBy(() -> useCase.execute(validCommand()))
           .isInstanceOf(PaymentFailedException.class);
 
       verify(orderRepository, never()).save(any());  // Order NOT persisted
   }
}
 
// Domain entity unit test — ZERO mocking
class OrderTest {
 
   @Test
   void confirm_pendingOrder_changesStatusToConfirmed() {
       Order order = Order.create(customerId, List.of(item1, item2));
       order.confirm();
       assertThat(order.getStatus()).isEqualTo(OrderStatus.CONFIRMED);
   }
 
   @Test
   void confirm_emptyOrder_throwsException() {
       Order order = Order.create(customerId, List.of());
       assertThatThrownBy(order::confirm)
           .isInstanceOf(EmptyOrderException.class);
   }
 
   @Test
   void cancel_shippedOrder_throwsException() {
       Order order = createShippedOrder();
       assertThatThrownBy(() -> order.cancel("Changed mind"))
           .isInstanceOf(IllegalOrderStateException.class);
   }
}