Software Dev March 19, 2026 20 min read Software Architecture Series

Table of Contents

1. The Architecture Rot Problem in Spring Boot Services
2. Hexagonal Architecture: Core Concepts
3. Project Structure and Package Design
4. The Domain Core: Pure Business Logic
5. Ports: The Interface Boundary
6. Adapters: Technology-Specific Implementations
7. Testing Strategy: Unit, Integration, and System
8. Common Failures and Anti-Patterns
9. Trade-offs and When NOT to Use Hexagonal Architecture
10. Key Takeaways

Real scenario: A fintech team needed to expose their payment processing logic via both a REST API and a Kafka consumer. The business logic was in a @Service class that injected a JPA repository and a Spring Security context — both unavailable in the Kafka consumer. They duplicated the business logic into a "Kafka service." Six months later, both diverged. Two bugs were fixed in the REST path but not the Kafka path. A compliance audit found the discrepancy.

                    DRIVING SIDE (Primary)
            [REST Adapter]   [Kafka Adapter]   [CLI Adapter]
                   ↓ uses          ↓ uses
              [Inbound Port / Use Case Interface]
                   ↓ implemented by
            ┌────────────────────────────┐
            │ DOMAIN CORE (Hexagon) │
            │ Entities, Domain Services │
            │ Business Rules & Logic │
            └────────────────────────────┘
                   ↑ uses (via interface)
              [Outbound Port / Repository Interface]
                   ↑ implemented by
  [JPA Adapter]     [HTTP Client Adapter]   [In-Memory Adapter]
                 DRIVEN SIDE (Secondary)

com.myapp.payments
├── domain/                          # Domain core (no Spring, no JPA)
│   ├── model/
│   │   ├── Payment.java             # Domain entity
│   │   ├── PaymentId.java           # Value object
│   │   └── PaymentStatus.java       # Domain enum
│   ├── service/
│   │   └── PaymentDomainService.java # Business logic
│   └── exception/
│       └── InsufficientFundsException.java
│
├── application/                     # Use cases (orchestration layer)
│   ├── port/
│   │   ├── in/                      # Inbound ports (use case interfaces)
│   │   │   ├── ProcessPaymentUseCase.java
│   │   │   └── GetPaymentStatusUseCase.java
│   │   └── out/                     # Outbound ports
│   │       ├── PaymentRepository.java
│   │       ├── NotificationPort.java
│   │       └── FraudCheckPort.java
│   └── service/
│       └── PaymentApplicationService.java  # Implements use cases
│
└── adapter/                         # All technology-specific code
    ├── in/
    │   ├── rest/                    # REST driving adapter
    │   │   ├── PaymentController.java
    │   │   └── dto/
    │   └── kafka/                   # Kafka driving adapter
    │       └── PaymentEventConsumer.java
    └── out/
        ├── persistence/             # JPA driven adapter
        │   ├── PaymentJpaRepository.java
        │   └── PaymentPersistenceAdapter.java
        ├── notification/            # Email/SMS driven adapter
        └── fraud/                   # External fraud API driven adapter

// Domain entity — no JPA, no Spring
public class Payment {
    private final PaymentId id;
    private final Money amount;
    private final AccountId senderId;
    private final AccountId receiverId;
    private PaymentStatus status;

    // Factory method enforces business invariants
    public static Payment create(Money amount, AccountId from, AccountId to) {
        if (amount.isNegativeOrZero()) {
            throw new InvalidPaymentAmountException(amount);
        }
        if (from.equals(to)) {
            throw new SelfTransferException(from);
        }
        return new Payment(PaymentId.generate(), amount, from, to,
                           PaymentStatus.PENDING);
    }

    public void approve() {
        if (this.status != PaymentStatus.PENDING) {
            throw new InvalidStateTransitionException(status, PaymentStatus.APPROVED);
        }
        this.status = PaymentStatus.APPROVED;
    }
}

// Inbound port — defines what the application can do
public interface ProcessPaymentUseCase {
    PaymentResult process(ProcessPaymentCommand command);
}

// Command object — value object, no Spring annotations
public record ProcessPaymentCommand(
    String senderId,
    String receiverId,
    BigDecimal amount,
    String currency
) {}

// Outbound port — defines what the application needs
// (Note: no JPA, no Spring, just a domain interface)
public interface PaymentRepository {
    void save(Payment payment);
    Optional<Payment> findById(PaymentId id);
    List<Payment> findPendingOlderThan(Duration age);
}

// Outbound port for fraud checking
public interface FraudCheckPort {
    FraudCheckResult check(PaymentId paymentId, Money amount, AccountId sender);
}

// REST driving adapter — Spring annotations live here, not in domain
@RestController
@RequestMapping("/api/payments")
@RequiredArgsConstructor
public class PaymentController {
    private final ProcessPaymentUseCase processPayment;  // Inbound port

    @PostMapping
    public ResponseEntity<PaymentResponse> createPayment(
            @RequestBody @Valid CreatePaymentRequest request) {
        ProcessPaymentCommand command = new ProcessPaymentCommand(
            request.senderId(), request.receiverId(),
            request.amount(), request.currency()
        );
        PaymentResult result = processPayment.process(command);
        return ResponseEntity.ok(PaymentResponse.from(result));
    }
}

// JPA driven adapter — implements outbound port
@Component
@RequiredArgsConstructor
class PaymentPersistenceAdapter implements PaymentRepository {
    private final PaymentJpaRepository jpaRepo;
    private final PaymentMapper mapper;

    @Override
    public void save(Payment payment) {
        jpaRepo.save(mapper.toJpaEntity(payment));
    }

    @Override
    public Optional<Payment> findById(PaymentId id) {
        return jpaRepo.findById(id.value())
            .map(mapper::toDomain);
    }
}

class PaymentTest {
    @Test
    void shouldRejectNegativeAmount() {
        assertThrows(InvalidPaymentAmountException.class, () ->
            Payment.create(Money.of(-10, "USD"), AccountId.of("A"), AccountId.of("B"))
        );
    }

    @Test
    void shouldRejectSelfTransfer() {
        assertThrows(SelfTransferException.class, () ->
            Payment.create(Money.of(100, "USD"), AccountId.of("A"), AccountId.of("A"))
        );
    }
}

@ExtendWith(MockitoExtension.class)
class PaymentApplicationServiceTest {
    @Mock PaymentRepository repository;
    @Mock FraudCheckPort fraudCheck;
    @Mock NotificationPort notifications;

    @InjectMocks PaymentApplicationService service;

    @Test
    void shouldSavePaymentAfterFraudCheckPasses() {
        when(fraudCheck.check(any(), any(), any()))
            .thenReturn(FraudCheckResult.SAFE);

        service.process(new ProcessPaymentCommand("A", "B", BigDecimal.TEN, "USD"));

        verify(repository).save(argThat(p -> p.getStatus() == PaymentStatus.APPROVED));
        verify(notifications).notifyPaymentInitiated(any());
    }
}

• The domain core contains zero Spring/JPA dependencies — it's pure Java testable with no Spring context.
• Inbound ports define what the application does (use case interfaces); outbound ports define what it needs (repository, notification interfaces).
• All Spring annotations live in adapters — never in domain or application layers.
• Map aggressively at adapter boundaries: domain ↔ JPA entity, domain ↔ DTO. Use MapStruct to eliminate boilerplate.
• The primary testability benefit: use case tests run with mocked ports in milliseconds, no Spring context needed.
• Apply hexagonal architecture to services with complex business logic and multiple input channels; avoid for simple CRUD services.

Related Posts

• Clean Architecture in Practice: Beyond the Theory
• Domain-Driven Design: Bounded Contexts and Aggregates
• Spring Boot Performance Tuning: From Dev to Production
• API Design Best Practices for Backend Engineers
• Data Management Patterns in Microservices

Back to Blog