Clean Architecture: Implementing Hexagonal (Ports & Adapters) in Spring Boot 4



Many enterprise Java applications start with clean code. Over time, teams add quick changes to meet tight deadlines. Business logic leaks into web controllers. JPA entity annotations bleed into domain calculations. Soon, simple changes cause regressions across the entire project.

Traditional three-tier architectures often cause this problem. In a standard Controller-Service-Repository model, dependencies point down toward the database. When your database schema changes, your business rules break. When you upgrade your web framework, your business logic needs edits. Unit testing also becomes slow because code requires heavy mocking or live databases.

Hexagonal Architecture (also known as the Ports and Adapters pattern) solves this architectural decay. Coined by Alistair Cockburn, this pattern inverts your dependencies. The core domain logic sits inside an isolated center. External technologies—like HTTP APIs, message brokers, and SQL databases—connect through boundary interfaces called ports.

In this guide, you will learn how to build a production-ready banking service with Hexagonal Architecture using Spring Boot 4 and Java 25. You will see how to isolate domain logic from framework annotations, configure Spring IoC factory beans, and write fast unit tests without Spring or databases.

Table of Contents

• What Is Hexagonal Architecture?
• Architectural Comparison: Layered vs Hexagonal vs Clean Architecture
• The Core: Building an Isolated Domain Layer in Java 25
• Inbound Ports: Defining Driving Use Cases
• Outbound Ports: The Service Provider Interface (SPI)
• Driving Adapters: Building the Spring MVC REST Layer
• Driven Adapters: Persistence with Spring Data JPA and Hibernate 7.1
• Spring Boot 4 Assembly: Inversion of Control Without Annotations
• End-to-End Execution Trace: Request to Persistence
• Testing Strategy: Zero-Mocking Domain and Integration Tests
• Real-World Enterprise Use Cases
• Production Guidelines and Best Practices
• Common Mistakes and How to Avoid Them
• Conclusion
• Frequently Asked Questions (FAQ)
• Resources & Companion Code

What Is Hexagonal Architecture?

Hexagonal Architecture divides a software system into two distinct regions: the inside and the outside. The inside contains pure domain models and business services. The outside contains infrastructure, databases, UI layers, message brokers, and third-party APIs.

The term “hexagon” does not mean your application has six sides. The shape represents multiple entry and exit points. An application needs connections for HTTP requests, queue messages, database queries, and cache lookups. The hexagon visually shows that each connection enters through a dedicated boundary.

Hexagonal Architecture relies on three primary concepts:

• The Domain Core: Plain Java objects (POJOs) that hold business rules, state transitions, and validation invariants. The core never imports Spring, Jakarta EE, Hibernate, or any external framework.
• Ports: Java interfaces that define boundaries. Inbound ports (driving) declare actions that external clients can trigger. Outbound ports (driven) declare operations the domain needs from external systems.
• Adapters: Concrete infrastructure implementations. A REST controller is a driving adapter that translates HTTP requests into inbound port method calls. A JPA repository adapter is a driven adapter that implements an outbound port to read and save database records.

This design enforces the Dependency Inversion Principle. High-level business rules do not depend on low-level infrastructure details. Both depend on abstract interfaces. The domain owns the port interfaces, and the external adapters adapt to the domain.

Architectural Comparison: Layered vs Hexagonal vs Clean Architecture

To choose the right pattern for your team, you must understand how Hexagonal Architecture compares to traditional layered designs and other clean architectural styles. Each style provides different trade-offs in complexity, speed, and long-term maintainability.

In traditional three-tier architectures, the database is the foundation of the system. Developers design database tables first. Then they create JPA entities, Spring Data repositories, service classes, and controllers. This database-first mindset creates tight coupling:

Hexagonal Architecture is the most practical form of Clean Architecture for Spring Boot applications. It avoids overly complex concentric layers while delivering complete isolation for your business rules.

The Core: Building an Isolated Domain Layer in Java 25

Let us implement a banking transfer feature. We start at the center of the hexagon: the domain model. In pure Hexagonal Architecture, this code contains no Spring annotations, no JPA annotations, and no third-party libraries.

We use Java 25 features like compact records and strongly typed identifiers to protect domain integrity. We start with the value object for account identification:

package com.webcodein.bank.domain.model;

import java.util.Objects;

public record AccountId(Long value) {

    public AccountId {
        Objects.requireNonNull(value, "Account ID must not be null");
        if (value <= 0) {
            throw new IllegalArgumentException("Account ID must be positive");
        }
    }
}

Next, we build the Account aggregate root. This aggregate encapsulates balance state and business invariants. Notice how the methods guard against invalid financial states:

package com.webcodein.bank.domain.model;

import java.math.BigDecimal;
import java.util.Objects;

public class Account {

    private final AccountId id;
    private BigDecimal balance;

    public Account(AccountId id, BigDecimal initialBalance) {
        this.id = Objects.requireNonNull(id, "Account ID cannot be null");
        this.balance = Objects.requireNonNull(initialBalance, "Initial balance cannot be null");
        if (initialBalance.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("Initial balance cannot be negative");
        }
    }

    public void withdraw(BigDecimal amount) {
        Objects.requireNonNull(amount, "Withdrawal amount cannot be null");
        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("Withdrawal amount must be greater than zero");
        }
        if (this.balance.compareTo(amount) < 0) {
            throw new InsufficientFundsException("Cannot withdraw " + amount + " from account balance " + balance);
        }
        this.balance = this.balance.subtract(amount);
    }

    public void deposit(BigDecimal amount) {
        Objects.requireNonNull(amount, "Deposit amount cannot be null");
        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("Deposit amount must be greater than zero");
        }
        this.balance = this.balance.add(amount);
    }

    public AccountId getId() {
        return id;
    }

    public BigDecimal getBalance() {
        return balance;
    }
}

When an invalid transaction occurs, the domain throws a domain-specific exception. This exception extends RuntimeException and contains clear error details:

package com.webcodein.bank.domain.model;

public class InsufficientFundsException extends RuntimeException {

    public InsufficientFundsException(String message) {
        super(message);
    }
}

Inbound Ports: Defining Driving Use Cases

Inbound ports represent the API of your core application. They define what actions the outside world can request. An inbound port is an interface that describes a specific business use case.

Here is our inbound use case interface for transferring money:

package com.webcodein.bank.domain.port.in;

import com.webcodein.bank.domain.model.AccountId;
import java.math.BigDecimal;

public interface TransferMoneyUseCase {

    boolean transfer(AccountId source, AccountId target, BigDecimal amount);
}

Next, we implement this interface in our pure domain service. Notice that TransferMoneyService has no Spring @Service or @Autowired annotations. It accepts its required dependencies through a standard Java constructor:

package com.webcodein.bank.domain.service;

import com.webcodein.bank.domain.model.Account;
import com.webcodein.bank.domain.model.AccountId;
import com.webcodein.bank.domain.port.in.TransferMoneyUseCase;
import com.webcodein.bank.domain.port.out.LoadAccountPort;
import com.webcodein.bank.domain.port.out.UpdateAccountStatePort;
import java.math.BigDecimal;
import java.util.Objects;

public class TransferMoneyService implements TransferMoneyUseCase {

    private final LoadAccountPort loadAccountPort;
    private final UpdateAccountStatePort updateAccountStatePort;

    public TransferMoneyService(LoadAccountPort loadAccountPort, UpdateAccountStatePort updateAccountStatePort) {
        this.loadAccountPort = Objects.requireNonNull(loadAccountPort, "LoadAccountPort cannot be null");
        this.updateAccountStatePort = Objects.requireNonNull(updateAccountStatePort, "UpdateAccountStatePort cannot be null");
    }

    @Override
    public boolean transfer(AccountId source, AccountId target, BigDecimal amount) {
        Account sourceAccount = loadAccountPort.loadAccount(source);
        Account targetAccount = loadAccountPort.loadAccount(target);

        sourceAccount.withdraw(amount);
        targetAccount.deposit(amount);

        updateAccountStatePort.update(sourceAccount);
        updateAccountStatePort.update(targetAccount);

        return true;
    }
}

Outbound Ports: The Service Provider Interface (SPI)

The domain service needs to load and persist accounts. However, it does not know whether accounts live in PostgreSQL, MongoDB, or an in-memory cache. To enforce this decoupling, the domain defines outbound ports.

In Hexagonal Architecture, the domain owns the port contracts. We split read operations and write operations into fine-grained interfaces:

package com.webcodein.bank.domain.port.out;

import com.webcodein.bank.domain.model.Account;
import com.webcodein.bank.domain.model.AccountId;

public interface LoadAccountPort {

    Account loadAccount(AccountId id);
}

And the port for updating state:

package com.webcodein.bank.domain.port.out;

import com.webcodein.bank.domain.model.Account;

public interface UpdateAccountStatePort {

    void update(Account account);
}

By keeping these interfaces small and focused, we follow the Interface Segregation Principle. Later, if we need an audit logger or an event bus, we can add a new outbound port without changing existing code.

Driving Adapters: Building the Spring MVC REST Layer

Now we step outside the hexagon. A driving adapter receives external requests and converts them into domain calls. In our web application, this is a Spring MVC REST controller.

The controller depends strictly on the inbound port interface (TransferMoneyUseCase), not on the concrete domain service class. It also handles web concerns like JSON deserialization and HTTP response status codes:

package com.webcodein.bank.adapter.in.web;

import com.webcodein.bank.domain.model.AccountId;
import com.webcodein.bank.domain.model.InsufficientFundsException;
import com.webcodein.bank.domain.port.in.TransferMoneyUseCase;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import java.math.BigDecimal;
import java.util.Map;

public record TransferRequest(Long source, Long target, BigDecimal amount) {}

@RestController
public class TransferController {

    private final TransferMoneyUseCase transferMoneyUseCase;

    public TransferController(TransferMoneyUseCase transferMoneyUseCase) {
        this.transferMoneyUseCase = transferMoneyUseCase;
    }

    @PostMapping("/api/transfers")
    public ResponseEntity<?> transfer(@RequestBody TransferRequest request) {
        transferMoneyUseCase.transfer(
            new AccountId(request.source()),
            new AccountId(request.target()),
            request.amount()
        );
        return ResponseEntity.ok(Map.of("status", "SUCCESS", "message", "Transfer completed successfully"));
    }

    @ExceptionHandler(InsufficientFundsException.class)
    public ResponseEntity<?> handleInsufficientFunds(InsufficientFundsException ex) {
        return ResponseEntity.badRequest().body(Map.of("status", "ERROR", "message", ex.getMessage()));
    }
}

Notice how clean the controller is. It does not perform business validation. It parses input, converts IDs into AccountId value objects, calls the use case, and maps exceptions to clean HTTP 400 responses.

Driven Adapters: Persistence with Spring Data JPA and Hibernate 7.1

On the outbound side, a driven adapter implements the outbound port interfaces. Our persistence adapter uses Spring Data JPA and Hibernate 7.1 to persist data in a relational database.

Crucially, the database entity is distinct from our domain model. We maintain a separate JPA entity class inside the persistence package:

package com.webcodein.bank.adapter.out.persistence;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import java.math.BigDecimal;

@Entity
@Table(name = "account")
class AccountJpaEntity {

    @Id
    private Long id;

    private BigDecimal balance;

    protected AccountJpaEntity() {
    }

    AccountJpaEntity(Long id, BigDecimal balance) {
        this.id = id;
        this.balance = balance;
    }

    Long getId() {
        return id;
    }

    BigDecimal getBalance() {
        return balance;
    }
}

We define a standard Spring Data repository interface. Because this repository is an internal implementation detail of the adapter, it has package-private visibility:

package com.webcodein.bank.adapter.out.persistence;

import org.springframework.data.jpa.repository.JpaRepository;

interface SpringDataAccountRepository extends JpaRepository<AccountJpaEntity, Long> {
}

Next, we create a dedicated mapper class. The mapper translates between the external database entity and the clean domain aggregate:

package com.webcodein.bank.adapter.out.persistence;

import com.webcodein.bank.domain.model.Account;
import com.webcodein.bank.domain.model.AccountId;
import org.springframework.stereotype.Component;

@Component
class AccountMapper {

    Account mapToDomainEntity(AccountJpaEntity entity) {
        return new Account(new AccountId(entity.getId()), entity.getBalance());
    }

    AccountJpaEntity mapToJpaEntity(Account account) {
        return new AccountJpaEntity(account.getId().getValue(), account.getBalance());
    }
}

Finally, we assemble the AccountPersistenceAdapter. This class implements both LoadAccountPort and UpdateAccountStatePort:

package com.webcodein.bank.adapter.out.persistence;

import com.webcodein.bank.domain.model.Account;
import com.webcodein.bank.domain.model.AccountId;
import com.webcodein.bank.domain.port.out.LoadAccountPort;
import com.webcodein.bank.domain.port.out.UpdateAccountStatePort;
import jakarta.persistence.EntityNotFoundException;
import org.springframework.stereotype.Component;

@Component
public class AccountPersistenceAdapter implements LoadAccountPort, UpdateAccountStatePort {

    private final SpringDataAccountRepository repository;
    private final AccountMapper mapper;

    public AccountPersistenceAdapter(SpringDataAccountRepository repository, AccountMapper mapper) {
        this.repository = repository;
        this.mapper = mapper;
    }

    @Override
    public Account loadAccount(AccountId id) {
        AccountJpaEntity entity = repository.findById(id.getValue())
            .orElseThrow(() -> new EntityNotFoundException("Account not found with ID: " + id.getValue()));
        return mapper.mapToDomainEntity(entity);
    }

    @Override
    public void update(Account account) {
        AccountJpaEntity entity = mapper.mapToJpaEntity(account);
        repository.save(entity);
    }
}

Spring Boot 4 Assembly: Inversion of Control Without Annotations

If our domain service contains no Spring annotations, how does the Spring container instantiate it and inject its dependencies? We use an external configuration class as our assembly harness.

In our configuration layer, we declare a @Configuration class with a @Bean method. Spring automatically supplies the LoadAccountPort and UpdateAccountStatePort implementations from the persistence adapter:

package com.webcodein.bank.configuration;

import com.webcodein.bank.domain.port.out.LoadAccountPort;
import com.webcodein.bank.domain.port.out.UpdateAccountStatePort;
import com.webcodein.bank.domain.service.TransferMoneyService;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class DomainConfig {

    @Bean
    public TransferMoneyService transferMoneyService(
            LoadAccountPort loadAccountPort,
            UpdateAccountStatePort updateAccountStatePort) {

        return new TransferMoneyService(loadAccountPort, updateAccountStatePort);
    }
}

This approach gives you the best of both worlds. The domain service remains a clean, portable Java class that compiles without Spring. Meanwhile, Spring Boot handles lifecycle management, connection pooling, and dependency injection seamlessly.

End-to-End Execution Trace: Request to Persistence

To see how all layers collaborate during runtime, let us walk through an end-to-end transfer execution trace.

1. HTTP Request: A client sends a POST /api/transfers request with a JSON payload specifying source account ID 1, target account ID 2, and amount $75.00.
2. Driving Adapter Parsing: The TransferController deserializes the JSON into a TransferRequest record and converts primitive IDs into AccountId value objects.
3. Inbound Port Call: The controller calls TransferMoneyUseCase.transfer(sourceId, targetId, amount).
4. Domain Orchestration: The TransferMoneyService receives the call and asks the LoadAccountPort to load both accounts.
5. Driven Adapter Retrieval: The AccountPersistenceAdapter calls Spring Data JPA, queries the database table, maps AccountJpaEntity records to domain Account objects, and returns them to the service.
6. Domain Business Logic: The Account aggregate executes invariants. It calls source.withdraw(75.00) (checking balance) and target.deposit(75.00).
7. Driven Adapter Persistence: The service calls UpdateAccountStatePort.update() for both accounts. The persistence adapter maps the updated models back to JPA entities and calls repository.save().
8. HTTP Response: The controller returns an HTTP 200 OK response with a success confirmation.

Testing Strategy: Zero-Mocking Domain and Integration Tests

One of the greatest benefits of Hexagonal Architecture is testability. Because your domain core depends only on interfaces, you can test complex business scenarios without Spring Boot, without Mockito, and without running a database.

1. Testing the Domain Without Frameworks

In our domain unit test, we implement a simple in-memory test double for the ports. The test runs in milliseconds:

package com.webcodein.bank.domain.service;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;

import com.webcodein.bank.domain.model.Account;
import com.webcodein.bank.domain.model.AccountId;
import com.webcodein.bank.domain.model.InsufficientFundsException;
import com.webcodein.bank.domain.port.out.LoadAccountPort;
import com.webcodein.bank.domain.port.out.UpdateAccountStatePort;
import java.math.BigDecimal;
import java.util.HashMap;
import java.util.Map;
import org.junit.jupiter.api.Test;

class TransferMoneyServiceTest {

    private final InMemoryAccounts accounts = new InMemoryAccounts();
    private final TransferMoneyService service = new TransferMoneyService(accounts, accounts);

    private final AccountId source = new AccountId(1L);
    private final AccountId target = new AccountId(2L);

    @Test
    void movesMoneyBetweenAccounts() {
        accounts.store.put(1L, new Account(source, new BigDecimal("100.00")));
        accounts.store.put(2L, new Account(target, new BigDecimal("10.00")));

        service.transfer(source, target, new BigDecimal("40.00"));

        assertThat(accounts.store.get(1L).getBalance()).isEqualByComparingTo("60.00");
        assertThat(accounts.store.get(2L).getBalance()).isEqualByComparingTo("50.00");
    }

    @Test
    void rejectsTransferWithInsufficientFunds() {
        accounts.store.put(1L, new Account(source, new BigDecimal("5.00")));
        accounts.store.put(2L, new Account(target, BigDecimal.ZERO));

        assertThatThrownBy(() -> service.transfer(source, target, new BigDecimal("40.00")))
            .isInstanceOf(InsufficientFundsException.class);
    }

    private static class InMemoryAccounts implements LoadAccountPort, UpdateAccountStatePort {
        final Map<Long, Account> store = new HashMap<>();

        @Override
        public Account loadAccount(AccountId id) {
            return store.get(id.value());
        }

        @Override
        public void update(Account account) {
            store.put(account.getId().value(), account);
        }
    }
}

2. Web-Layer Testing with MockMvc and @MockitoBean

In Spring Boot 4, we use @WebMvcTest and @MockitoBean to test web adapters in isolation:

package com.webcodein.bank.adapter.in.web;

import com.webcodein.bank.domain.model.AccountId;
import com.webcodein.bank.domain.port.in.TransferMoneyUseCase;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.servlet.MockMvc;

import java.math.BigDecimal;

import static org.mockito.Mockito.verify;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest(TransferController.class)
class TransferControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private TransferMoneyUseCase transferMoneyUseCase;

    @Test
    void shouldReturn200WhenTransferSucceeds() throws Exception {
        String json = """
                {"source": 1, "target": 2, "amount": 75.50}
                """;

        mockMvc.perform(post("/api/transfers")
                .contentType(MediaType.APPLICATION_JSON)
                .content(json))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.status").value("SUCCESS"));

        verify(transferMoneyUseCase).transfer(
                new AccountId(1L), new AccountId(2L), new BigDecimal("75.50"));
    }
}

Real-World Enterprise Use Cases

Hexagonal Architecture provides significant value in complex enterprise domains where software must outlive infrastructure choices.

1. Core Banking & Multi-Currency Ledgers

In financial institutions, core banking rules change based on strict government regulations and compliance audits. Databases frequently migrate from legacy mainframe DB2 instances to modern cloud PostgreSQL clusters. Hexagonal Architecture allows engineers to swap the database adapter while proving mathematically that financial debit/credit calculations remain unchanged.

2. Healthcare EHR Gateways (HL7 & FHIR Standards)

Healthcare backends must communicate with legacy hospital systems using HL7 v2 pipe-delimited feeds and modern mobile apps using FHIR JSON REST APIs. By treating HL7 feeds and FHIR endpoints as separate driving adapters, both protocols feed into the same clinical observation domain core without duplicating patient care rules.

3. Multi-Tenant SaaS with Pluggable Payment Providers

SaaS platforms often need to support multiple payment processors (such as Stripe, Adyen, and PayPal) based on tenant country and subscription tier. An outbound PaymentGatewayPort lets the application swap payment vendors via runtime adapter selection while keeping the billing subscription lifecycle intact.

Production Guidelines and Best Practices

Follow these proven guidelines when implementing Hexagonal Architecture in enterprise Spring Boot projects:

• Package by Feature (or Component): Avoid placing all ports in one generic global package. Group ports, models, and adapters by domain concept (e.g., com.company.account.* and com.company.loan.*).
• Keep Port Interfaces Cohesive: Do not create a single giant port interface with twenty methods. Follow the Role Interface pattern and create small, focused interfaces for distinct use cases.
• Enforce Boundaries with ArchUnit: Add automated architectural unit tests using ArchUnit. Verify in CI that no classes in domain.. package import packages starting with org.springframework.. or jakarta.persistence...
• GraalVM Native Image Readiness: Because the domain core relies on pure Java POJOs without reflection or proxies, it compiles to GraalVM native image binaries cleanly and starts in milliseconds. Check our guide on GraalVM Native Images in Spring Boot 4 for optimization tips.
• Combine with Event Sourcing: For high-audit transactional systems, outbound ports can dispatch domain events directly to Kafka. See our guide on CQRS and Event Sourcing in Spring Boot 4.

Common Mistakes and How to Avoid Them

When teams adopt Hexagonal Architecture, they often stumble into three common traps:

Pitfall 1: Leaking Framework Annotations into the Domain

Developers often get lazy and add @Service, @Transactional, or @Entity annotations directly onto domain classes. This completely destroys the architectural boundary. Once framework annotations enter the domain, your business logic becomes tightly coupled to framework upgrade cycles.

Fix: Keep domain models and domain services strictly free of framework annotations. Use Spring @Configuration classes to assemble beans, and handle transaction demarcation at the adapter or application service layer.

Pitfall 2: Reusing JPA Entities as Domain Models

To avoid writing mapper code, some teams use JPA entities inside their use cases and domain models. However, JPA entities require default no-arg constructors, mutable setters, and relationship proxies. This breaks domain invariants and can trigger lazy-loading exceptions outside active sessions.

Fix: Always maintain separate domain models and database entities. The small cost of writing mapping methods guarantees complete isolation for your business rules.

Pitfall 3: Port Proliferation (The 1-to-1 Mapping Trap)

Creating a unique inbound port and outbound port for every single CRUD operation creates unnecessary ceremony. If an operation only reads data for a simple dashboard display, forcing it through four layers of ports and adapters adds boilerplate without benefit.

Fix: Apply Hexagonal Architecture where business logic is rich and complex. For simple read-only queries, consider lightweight CQRS query handlers that read directly from repositories.

Conclusion

Hexagonal Architecture shifts your mindset from framework-driven development to domain-driven craftsmanship. By treating Spring Boot 4, Hibernate 7, and web protocols as external implementation details, you protect your core business assets from technical debt and infrastructure churn.

Your business logic becomes self-contained, easy to reason about, and capable of executing in pure unit tests in under a second. When the day comes to swap your persistence layer, add a message broker, or migrate to a new framework version, your core domain will remain untouched.

Frequently Asked Questions (FAQ)

Is Hexagonal Architecture overkill for simple CRUD applications?

Yes. If your application simply reads and writes database records without complex calculations or validations, traditional three-tier architecture is faster and simpler. Hexagonal Architecture provides maximum return on investment when business rules are complex and long-term maintainability is critical.

How do I handle transactions in Hexagonal Architecture?

You can manage transactions in two ways. The most common Spring Boot approach is to place @Transactional on the configuration bean declaration or on an application service wrapper. Alternatively, you can use programmatic transaction demarcation (such as Spring’s TransactionTemplate) inside an outbound adapter.

Does mapping between domain models and JPA entities impact performance?

In standard business applications, mapping overhead is negligible (typically sub-microsecond in modern JVMs). The database network I/O and SQL execution take orders of magnitude longer. For extreme high-throughput pipelines, automated byte-code mappers like MapStruct generate zero-overhead compiled mapping code.

What is the difference between Inbound and Outbound Ports?

Inbound (driving) ports define what the system does. External clients (like REST controllers or message listeners) call inbound ports to execute use cases. Outbound (driven) ports define what the system needs. Domain services call outbound ports to load data, save state, or dispatch events to external infrastructure.

Resources & Companion Code

• Companion Workshop Code on GitHub
• Alistair Cockburn: The Original Hexagonal Architecture Paper
• Spring Boot 4 Official Documentation
• Hibernate ORM 7.1 Reference Guide
• Advanced Kafka: The Transactional Outbox Pattern with Spring Boot 4
• Zero-Trust Architecture in Spring Boot 4 with Spring Security 7