Clean Architecture in Java: Separating Domain Logic from the Framework

The Four Layers

            ┌──────────────────────────────────┐
            │        Frameworks & Drivers      │  (Spring, JPA, REST)
            │  ┌─────────────────────────────┐ │
            │  │    Interface Adapters       │ │  (Controllers, Repositories)
            │  │  ┌───────────────────────┐  │ │
            │  │  │   Application/UseCases│  │ │  (Business Workflow)
            │  │  │  ┌─────────────────┐  │  │ │
            │  │  │  │     Domain      │  │  │ │  (Entities, Rules)
            │  │  │  └─────────────────┘  │  │ │
            │  │  └───────────────────────┘  │ │
            │  └─────────────────────────────┘ │
            └──────────────────────────────────┘

Dependency rule: arrows always point INWARD.
The domain knows neither Spring nor JPA.

Project Structure

order-service/
└── src/main/java/com/zelkulon/order/
    ├── domain/                    ← Innermost layer (no Spring!)
    │   ├── model/
    │   │   └── Order.java
    │   └── valueobject/
    │       └── Money.java
    │
    ├── application/               ← Use Cases
    │   ├── port/
    │   │   ├── in/                ← Incoming ports
    │   │   │   └── PlaceOrderUseCase.java
    │   │   └── out/               ← Outgoing ports
    │   │       └── OrderRepository.java
    │   └── service/
    │       └── PlaceOrderService.java
    │
    └── adapter/                   ← Outermost layer
        ├── in/web/
        │   └── OrderController.java
        └── out/persistence/
            ├── OrderJpaEntity.java  ← JPA only here!
            └── OrderPersistenceAdapter.java

The Domain: Spring-Free

// NO Spring annotations, NO JPA!
public class Order {

    private final OrderId id;
    private final CustomerId customerId;
    private final List<OrderItem> items;
    private OrderStatus status;

    public Order(OrderId id, CustomerId customerId, List<OrderItem> items) {
        if (items == null || items.isEmpty())
            throw new OrderException("Mindestens ein Artikel nötig");
        this.id     = id;
        this.items  = List.copyOf(items);
        this.status = OrderStatus.PENDING;
    }

    // Domain logic belongs in the domain!
    public void confirm() {
        if (this.status != OrderStatus.PENDING)
            throw new OrderException("Nur PENDING kann bestätigt werden");
        this.status = OrderStatus.CONFIRMED;
    }
}

// Value Object (Record)
public record Money(BigDecimal amount, Currency currency) {
    public Money {
        if (amount.compareTo(BigDecimal.ZERO) < 0)
            throw new IllegalArgumentException("Betrag darf nicht negativ sein");
    }
    public Money add(Money other) {
        return new Money(amount.add(other.amount), currency);
    }
}

Ports and Use Case

// Incoming port (Use Case Interface)
public interface PlaceOrderUseCase {
    OrderId placeOrder(PlaceOrderCommand command);
}

// Use Case Implementation
@UseCase  // custom annotation, semantically clearer than @Service
@Transactional
@RequiredArgsConstructor
public class PlaceOrderService implements PlaceOrderUseCase {

    private final OrderRepository orderRepository;   // Interface!
    private final PaymentGateway  paymentGateway;    // Interface!

    @Override
    public OrderId placeOrder(PlaceOrderCommand command) {
        var order = new Order(
            OrderId.newId(), command.customerId(), mapItems(command)
        );
        OrderId saved = orderRepository.save(order);
        paymentGateway.initiatePayment(order);
        return saved;
    }
}

Dependency Inversion Visualized

Without Clean Architecture:            With Clean Architecture:

Controller                          Controller
    │                                   │
    ▼                                   ▼ (implements)
OrderService ◄── JPA/DB            PlaceOrderUseCase (Port)
    │                                   ▲ (implements)
    ▼                                   │
JpaRepository                       PlaceOrderService
                                        │
                                    OrderRepository (Port)
                                        ▲ (implements)
                                        │
                                    OrderPersistenceAdapter
                                        │
                                    JpaRepository

Summary

• Testability: Domain and use cases testable without Spring (pure JUnit tests)
• Maintainability: Database changes do not affect the domain
• Replaceability: Framework migration possible without domain changes
• Readability: Every class has a clearly defined responsibility
• Longevity: Well-structured projects remain maintainable for years