Refactoring a Legacy Spring Boot Monolith to Hexagonal Architecture

Software architecture changes over time. When you bootstrap a new Spring Boot application, the traditional three-tier layered architecture—Controller, Service, Repository—feels natural, clean, and highly productive. However, as business requirements evolve, team sizes expand, and enterprise codebases grow, this simple structure frequently deteriorates into what software engineers call a "Big Ball of Mud."

In a typical legacy monolith, business rules become hopelessly entangled with framework-specific libraries. Database entities with JPA annotations leak directly into web controllers. Persistence logic bleeds into service layers, and core business rules cannot be tested without spinning up full Spring application contexts or complex mocking frameworks. Upgrading between major framework versions (such as moving from Spring Boot 3 to Spring Boot 4) turns into a high-risk nightmare.

To break free from framework lock-in and spaghetti code, modern enterprise engineering teams turn to Hexagonal Architecture (also known as Ports and Adapters). In this practical guide, we will walk step-by-step through refactoring a legacy Spring Boot application to a clean Hexagonal Architecture using Java 25 and Spring Boot 4. We will isolate pure business logic, invert infrastructure dependencies, and safeguard architectural boundaries with automated ArchUnit tests.

Table of Contents

• The Legacy Monolith Trap: Why Layered Architectures Decay
• Comparative Analysis: Software Architecture Paradigms
• Hexagonal Architecture Core Concepts: Ports, Adapters, and Inversion
• End-to-End Hexagonal System Architecture Overview
• Analyzing the Legacy Monolith Codebase
• Step 1: Carving Out the Pure Java 25 Domain Model
• Step 2: Defining Driving and Driven Ports
• Step 3: Implementing Use Case Services in the Application Layer
• Step 4: Building Driving Web Adapters (REST API)
• Step 5: Building Driven Persistence Adapters (Spring Data JPA)
• The Strangler Fig Migration: Zero-Downtime Transition
• Enterprise Use Cases: Banking, E-Commerce, and Healthcare
• Production Readiness: ArchUnit Governance & Testing
• Common Pitfalls and How to Fix Them
• Frequently Asked Questions (FAQ)
• Conclusion and Next Steps
• References and Companion Code

The Legacy Monolith Trap: Why Layered Architectures Decay

The standard three-tier architecture has been the default structure for enterprise Java systems for two decades. The flow appears logical at first glance: the Web Controller handles HTTP serialization, the Service layer coordinates business workflows, and the Repository executes SQL against the database.

However, this design suffers from a fatal structural flaw: the database is at the center of the architecture. In traditional layered projects, dependencies point downward toward the database: Web -> Service -> Repository -> Database Entity. Because the persistence layer is at the bottom, developers design database tables first. Then, they map those tables directly to JPA entities (annotated with @Entity, @Table, and @Id), and pass those entities directly into the Service layer and even out of the Controller.

This inverted priority creates severe architectural debt:

• Leaky Abstractions: Business entities are constrained by database design rather than business rules. Fields cannot easily enforce invariants because JPA requires default no-argument constructors and mutable getters/setters.
• Bloated Service Classes: Services become procedural "Transaction Scripts" spanning thousands of lines. They perform validation, data transformation, HTTP header checking, SQL queries, and notification dispatching in a single massive method.
• Slow, Fragile Testing: Testing a business calculation requires launching the full Spring context, an in-memory database, and several mock objects. Developers write fewer unit tests because tests take minutes instead of milliseconds.
• Framework Entrapment: The core business value of your company becomes locked into specific versions of Spring, Hibernate, or Jackson. Replacing a database engine or upgrading to a major framework version becomes an overwhelming engineering effort.

Comparative Analysis: Software Architecture Paradigms

To understand where Hexagonal Architecture fits relative to other architectural patterns, examine the comparative matrix below. It evaluates six architectural approaches across coupling, framework independence, testability, and refactoring effort.

Hexagonal Architecture Core Concepts: Ports, Adapters, and Inversion

Created by Alistair Cockburn in 2005, Hexagonal Architecture rests on a simple yet profound premise: an application should be equally drivable by users, programs, automated tests, or batch scripts, and developed and tested in isolation from its eventual run-time devices and databases.

The architecture is composed of three fundamental elements:

1. The Hexagon (Core Domain & Application Layer): The inside of the hexagon contains your business logic. It knows nothing about the web, HTTP, REST, JSON, SQL, or Spring. It is written in pure Java 25. Inside, you define your business entities, value objects, and business rules.
2. Ports (The Interfaces): Ports are Java interfaces that define the boundaries of the hexagon. There are two kinds of ports:
   • Driving Ports (Inbound / Input): Interfaces that describe what external actors want the application to do (e.g., RegisterUserUseCase). The application layer implements these ports.
   • Driven Ports (Outbound / Output): Interfaces that describe what the application needs from external tools (e.g., UserRepositoryPort, EmailNotificationPort). The application layer defines these interfaces, but external adapters implement them.
3. Adapters (The Infrastructure): Adapters translate technical protocols into domain language. There are two types:
   • Driving Adapters (Inbound): Convert external triggers (like an HTTP POST request or a Kafka message) into a call to an inbound port. Examples include Spring MVC @RestController classes.
   • Driven Adapters (Outbound): Implement outbound ports to interact with external systems. Examples include Spring Data JPA repositories, AWS S3 clients, or SendGrid email senders.

By applying the Dependency Inversion Principle (DIP), the direction of control and dependencies is inverted. Instead of the business service depending on a database repository, the business service defines a port interface. The database adapter then depends on the port. As a result, the database becomes a pluggable detail rather than the foundation of the system.

End-to-End Hexagonal System Architecture Overview

Figure 3 illustrates the full target architecture of our refactored Spring Boot 4 application.

Notice how external technologies are strictly isolated on the periphery:

• The Driving Web Adapter (Spring MVC) receives HTTP JSON requests, converts them into command objects, and invokes the RegisterUserUseCase port.
• The Application Service orchestrates domain entities, applies business validations, and invokes the outbound UserRepositoryPort.
• The Driven Persistence Adapter implements UserRepositoryPort, maps the pure domain model into a JPA entity, persists it via Spring Data JPA, and returns the result.

Analyzing the Legacy Monolith Codebase

To understand the refactoring journey, let us examine the legacy monolith code from our companion workshop repository. The legacy package structure is completely flat and coupled:

package com.webcodein.workshop.legacy;

import jakarta.persistence.*;

@Entity
@Table(name = "legacy_users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String username;
    private String email;

    public User() {}

    public User(String username, String email) {
        this.username = username;
        this.email = email;
    }

    public Long getId() { return id; }
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

Next, examine the legacy service. It is directly tied to Spring’s @Service and injects the Spring Data JPA repository:

package com.webcodein.workshop.legacy;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class LegacyUserService {

    private final LegacyUserRepository userRepository;

    public LegacyUserService(LegacyUserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Transactional
    public User registerUser(String username, String email) {
        // Business rule mixed with persistence logic
        if (username == null || username.isBlank()) {
            throw new IllegalArgumentException("Username cannot be empty");
        }
        if (email == null || !email.contains("@")) {
            throw new IllegalArgumentException("Invalid email format");
        }
        
        User user = new User(username, email);
        return userRepository.save(user);
    }
}

Notice the critical defects in this legacy design:

1. The User class is both a business entity and a database table definition. If we alter the database table structure, we risk breaking domain logic.
2. Validation is performed procedurally inside the service instead of being encapsulated inside the entity.
3. The service cannot be tested without either mocking the JPA repository or bootstrapping Spring Data.

Step 1: Carving Out the Pure Java 25 Domain Model

The first and most critical refactoring step is extracting the domain entity. In Hexagonal Architecture, domain classes must be 100% pure Java. They must not contain any annotations from jakarta.persistence.*, org.springframework.*, or com.fasterxml.jackson.*.

Here is our refactored domain model inside package com.webcodein.workshop.refactored.domain:

package com.webcodein.workshop.refactored.domain;

public class User {

    private final Long id;
    private final String username;
    private final String email;

    // Factory method for creating new users with domain invariant validation
    public static User createNew(String username, String email) {
        validateUsername(username);
        validateEmail(email);
        return new User(null, username, email);
    }

    // Factory method for reconstituting an existing user from storage
    public static User reconstitute(Long id, String username, String email) {
        if (id == null) {
            throw new IllegalArgumentException("Existing user must have a valid identifier");
        }
        return new User(id, username, email);
    }

    private User(Long id, String username, String email) {
        this.id = id;
        this.username = username;
        this.email = email;
    }

    private static void validateUsername(String username) {
        if (username == null || username.trim().isEmpty()) {
            throw new IllegalArgumentException("Username cannot be blank");
        }
        if (username.length() < 3) {
            throw new IllegalArgumentException("Username must contain at least 3 characters");
        }
    }

    private static void validateEmail(String email) {
        if (email == null || !email.matches("^[A-Za-z0-9+_.-]+@(.+)$")) {
            throw new IllegalArgumentException("Invalid email address format");
        }
    }

    public Long getId() { return id; }
    public String getUsername() { return username; }
    public String getEmail() { return email; }
}

Look closely at the design improvements:

• Immutability: The fields are final, eliminating unpredictable state mutations.
• Self-Encapsulated Invariants: The User entity validates its own constraints upon instantiation. It is mathematically impossible to create an invalid User in memory.
• Zero Framework Coupling: This class compiles with standard Java 25. It will run in any JVM environment without Spring, Hibernate, or application servers.

Step 2: Defining Driving and Driven Ports

Next, we establish the boundaries of the hexagon by defining our inbound and outbound ports.

Inbound Driving Port: The Use Case Interface

Inbound ports represent the capabilities offered by our application. We create a dedicated interface for each distinct use case:

package com.webcodein.workshop.refactored.application;

import com.webcodein.workshop.refactored.domain.User;

public interface RegisterUserUseCase {
    User register(String username, String email);
}

Outbound Driven Port: The Persistence SPI

Outbound ports declare what external services our business logic requires. Notice that the port uses the pure domain User model, not a JPA entity:

package com.webcodein.workshop.refactored.domain.port;

import com.webcodein.workshop.refactored.domain.User;
import java.util.Optional;

public interface UserRepositoryPort {
    User save(User user);
    Optional<User> findById(Long id);
    Optional<User> findByUsername(String username);
}

Step 3: Implementing Use Case Services in the Application Layer

With our ports defined, we implement the business workflow inside the application layer. The RegisterUserService implements the driving port RegisterUserUseCase and invokes the driven port UserRepositoryPort:

package com.webcodein.workshop.refactored.application;

import com.webcodein.workshop.refactored.domain.User;
import com.webcodein.workshop.refactored.domain.port.UserRepositoryPort;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class RegisterUserService implements RegisterUserUseCase {

    private final UserRepositoryPort userRepositoryPort;

    public RegisterUserService(UserRepositoryPort userRepositoryPort) {
        this.userRepositoryPort = userRepositoryPort;
    }

    @Override
    @Transactional
    public User register(String username, String email) {
        // Enforce business rule: Username must be unique
        userRepositoryPort.findByUsername(username).ifPresent(existing -> {
            throw new IllegalStateException("Username '" + username + "' is already taken");
        });

        // Instantiate domain model with business validation
        User newUser = User.createNew(username, email);

        // Persist via outbound port
        return userRepositoryPort.save(newUser);
    }
}

Because RegisterUserService depends only on UserRepositoryPort, we can write blazing-fast unit tests using simple in-memory stubs or Mockito without loading Spring:

@Test
void shouldRegisterUserSuccessfully() {
    UserRepositoryPort port = Mockito.mock(UserRepositoryPort.class);
    RegisterUserUseCase useCase = new RegisterUserService(port);
    
    Mockito.when(port.save(any(User.class)))
           .thenAnswer(invocation -> invocation.getArgument(0));

    User user = useCase.register("alex", "alex@example.com");
    assertThat(user.getUsername()).isEqualTo("alex");
}

Step 4: Building Driving Web Adapters (REST API)

The inbound web adapter is responsible for handling incoming HTTP requests. It deserializes input parameters, calls the inbound use case port, and converts the resulting domain entity into an HTTP response DTO.

package com.webcodein.workshop.refactored.adapter.in;

import com.webcodein.workshop.refactored.application.RegisterUserUseCase;
import com.webcodein.workshop.refactored.domain.User;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserWebAdapter {

    private final RegisterUserUseCase registerUserUseCase;

    public UserWebAdapter(RegisterUserUseCase registerUserUseCase) {
        this.registerUserUseCase = registerUserUseCase;
    }

    @PostMapping
    public ResponseEntity<UserResponse> register(
            @RequestParam("username") String username,
            @RequestParam("email") String email) {

        User user = registerUserUseCase.register(username, email);
        return ResponseEntity.ok(new UserResponse(user.getId(), user.getUsername(), user.getEmail()));
    }
}

The response DTO isolates the HTTP API contract from the internal domain model:

package com.webcodein.workshop.refactored.adapter.in;

public record UserResponse(Long id, String username, String email) {}

Step 5: Building Driven Persistence Adapters (Spring Data JPA)

The outbound persistence adapter bridges the domain’s UserRepositoryPort to the relational database. It contains three distinct elements:

1. A dedicated JPA entity (UserJpaEntity) decorated with Hibernate annotations.
2. A standard Spring Data JPA interface (SpringDataUserRepository).
3. An adapter class (UserRepositoryAdapter) that implements UserRepositoryPort and maps between domain models and JPA entities.

First, the JPA entity:

package com.webcodein.workshop.refactored.adapter.out;

import jakarta.persistence.*;

@Entity
@Table(name = "users")
public class UserJpaEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String username;

    @Column(nullable = false)
    private String email;

    public UserJpaEntity() {}

    public UserJpaEntity(Long id, String username, String email) {
        this.id = id;
        this.username = username;
        this.email = email;
    }

    public Long getId() { return id; }
    public String getUsername() { return username; }
    public String getEmail() { return email; }
}

Next, the Spring Data repository:

package com.webcodein.workshop.refactored.adapter.out;

import org.springframework.data.jpa.repository.JpaRepository;
import java.util.Optional;

public interface SpringDataUserRepository extends JpaRepository<UserJpaEntity, Long> {
    Optional<UserJpaEntity> findByUsername(String username);
}

Finally, the adapter that implements the driven port:

package com.webcodein.workshop.refactored.adapter.out;

import com.webcodein.workshop.refactored.domain.User;
import com.webcodein.workshop.refactored.domain.port.UserRepositoryPort;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class UserRepositoryAdapter implements UserRepositoryPort {

    private final SpringDataUserRepository springDataUserRepository;

    public UserRepositoryAdapter(SpringDataUserRepository springDataUserRepository) {
        this.springDataUserRepository = springDataUserRepository;
    }

    @Override
    public User save(User user) {
        UserJpaEntity entity = new UserJpaEntity(user.getId(), user.getUsername(), user.getEmail());
        UserJpaEntity saved = springDataUserRepository.save(entity);
        return User.reconstitute(saved.getId(), saved.getUsername(), saved.getEmail());
    }

    @Override
    public Optional<User> findById(Long id) {
        return springDataUserRepository.findById(id)
                .map(e -> User.reconstitute(e.getId(), e.getUsername(), e.getEmail()));
    }

    @Override
    public Optional<User> findByUsername(String username) {
        return springDataUserRepository.findByUsername(username)
                .map(e -> User.reconstitute(e.getId(), e.getUsername(), e.getEmail()));
    }
}

The Strangler Fig Migration: Zero-Downtime Transition

In real-world enterprise applications, you cannot pause business feature delivery for six months to execute a complete architectural rewrite. The safest and most effective migration strategy is the Strangler Fig Pattern. Figure 4 illustrates the four progressive phases of refactoring a legacy monolith into hexagonal architecture.

Here is how to execute the migration safely without disrupting production traffic:

1. Phase 1: Identify Invariants & Boundaries: Pick a single, high-value business capability (such as User Registration). Analyze its business rules and separate them from HTTP and database concerns.
2. Phase 2: Carve Out Domain & Ports: Create the new hexagonal package tree alongside the legacy code. Define the pure domain model, the inbound use case port, and the outbound persistence port.
3. Phase 3: Implement Adapters & Invert Dependencies: Implement the persistence adapter using Spring Data. Implement the web adapter. Wire the legacy controller to forward traffic to the new use case port. Run automated integration tests comparing legacy vs hexagonal behavior.
4. Phase 4: Deprecate Legacy Code & Apply Guardrails: Switch 100% of production traffic to the new web adapter. Delete the legacy service and legacy entity classes. Activate ArchUnit tests to prevent future architectural violations.

Enterprise Use Cases: Banking, E-Commerce, and Healthcare

Hexagonal Architecture provides tremendous return on investment across several mission-critical enterprise domains:

1. Core Banking Ledger Systems

In financial banking engines, money transfer calculations and accounting invariants must remain infallible. If a database vendor deprecates a driver or the cloud team migrates from Oracle to PostgreSQL, the financial accounting logic must not change. Hexagonal architecture encapsulates double-entry bookkeeping rules inside the pure domain core, making database transitions frictionless.

2. High-Scale E-Commerce Multi-Gateway Checkout

E-commerce checkout platforms must integrate with multiple payment processors (Stripe, PayPal, Adyen, Apple Pay) and dynamically route payments depending on customer geography. In a legacy monolith, payment vendor SDKs are tightly coupled to order services. In Hexagonal Architecture, the order service interacts with a single PaymentProcessorPort. Each vendor is implemented as a separate plug-and-play outbound adapter.

3. Healthcare Electronic Health Record (EHR) Exchanges

Healthcare providers exchange medical records across divergent protocols: HL7, FHIR, REST, and SOAP. By placing the clinical domain model at the center of the hexagon, medical validation rules remain constant while disparate inbound adapters ingest records from hospital networks, telemedicine apps, and regional labs seamlessly.

Production Readiness: ArchUnit Governance & Testing

The greatest threat to Hexagonal Architecture is developer convenience. Under intense deadline pressure, a developer might accidentally import org.springframework.stereotype.Service into the domain package, or pass a JPA entity directly into a domain method.

To permanently protect your architecture, enforce structural boundaries using ArchUnit. As detailed in our guide on Enforcing Hexagonal Architecture with ArchUnit, you can run automated architecture tests during standard Maven builds.

Add the following ArchUnit test to your workshop test suite:

package com.webcodein.workshop;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

@AnalyzeClasses(packages = "com.webcodein.workshop.refactored", importOptions = ImportOption.DoNotIncludeTests.class)
public class HexagonalArchitectureRulesTest {

    @ArchTest
    static final ArchRule domainMustNotDependOnFrameworks =
            noClasses()
                    .that().resideInAPackage("..domain..")
                    .should().dependOnClassesThat()
                    .resideInAnyPackage("org.springframework..", "jakarta.persistence..", "com.fasterxml.jackson..");

    @ArchTest
    static final ArchRule domainMustNotDependOnAdapters =
            noClasses()
                    .that().resideInAPackage("..domain..")
                    .should().dependOnClassesThat()
                    .resideInAPackage("..adapter..");
}

If any developer imports Spring or JPA annotations inside the domain, mvn test fails immediately, breaking the CI/CD pipeline before flawed code reaches production.

Furthermore, combine ArchUnit with real-world integration testing using PostgreSQL Testcontainers as explored in Modern Local Development with Testcontainers and TDD with Spring Boot 4: The Zero-Mocking Approach to verify complete end-to-end functionality.

Common Pitfalls and How to Fix Them

Pitfall 1: Leaking JPA Annotations into the Domain Model

The Problem: Developers want to avoid writing separate DTOs and mappers, so they put @Entity and @Table annotations directly on the domain User class.

The Consequence: The domain model becomes constrained by JPA rules (requiring default constructors, non-final fields, and relationship proxies), destroying domain encapsulation.

The Fix: Maintain strict separation. Keep User as a pure Java class in domain, and maintain UserJpaEntity inside adapter/out/persistence.

Pitfall 2: Creating 1:1 CRUD Ports for Every Entity

The Problem: Developers generate generic ports with findAll(), deleteById(), update(), mimicking standard database tables.

The Consequence: Ports become anemic pass-through layers that leak database thinking into the domain core.

The Fix: Design ports based on business intent and specific use cases (e.g., RegisterUserUseCase, SuspendAccountUseCase), not table CRUD operations.

Pitfall 3: Managing Database Transactions Inside Domain Entities

The Problem: Attempting to place Spring’s @Transactional annotation on domain methods.

The Consequence: Violates domain framework independence.

The Fix: Manage database transaction boundaries at the application service layer (on RegisterUserService) or use programmatic transaction management within the adapter layer.

Frequently Asked Questions (FAQ)

What is the difference between Hexagonal Architecture and Clean Architecture?

Hexagonal Architecture (Ports and Adapters) and Clean Architecture share the same underlying goal: inverting dependencies to protect business logic from technical infrastructure. Hexagonal Architecture focuses on the boundary between inside (domain) and outside (adapters) via ports. Clean Architecture specifies four concentric layers (Entities, Use Cases, Interface Adapters, Frameworks). In practice, both architectures follow identical dependency inversion principles.

Does Hexagonal Architecture cause excessive code duplication?

Hexagonal Architecture requires maintaining separate domain models, JPA entities, and API DTOs, along with mapping logic. While this introduces slightly more initial code, it provides total decoupling. When database schemas or API contracts change, your core business logic remains untouched, saving hundreds of engineering hours during enterprise maintenance.

How does Hexagonal Architecture accelerate developer unit tests?

Because the domain core and use case services have zero dependencies on Spring or JPA, developers can test business logic using pure JUnit 5 tests. These tests execute in sub-millisecond times without bootstrapping Spring application contexts or launching database containers.

Should every Spring Boot microservice use Hexagonal Architecture?

No. For simple CRUD microservices, database reporting pipelines, or temporary prototypes, traditional layered architecture or Spring Data REST is perfectly adequate. Hexagonal Architecture is strongly recommended for core business domains, complex workflows, and long-lived enterprise applications that require frequent feature additions and high testability.

How does Hexagonal Architecture facilitate Spring Boot 4 upgrades?

When upgrading across major framework releases (such as Spring Boot 3 to Spring Boot 4 on Java 25), only the outer adapter layer needs adjustments. Your core business rules, domain entities, and use case services remain 100% untouched and unaffected by framework breaking changes.

Conclusion and Next Steps

Refactoring a legacy Spring Boot monolith to Hexagonal Architecture transforms a fragile, database-coupled application into a resilient, maintainable, and highly testable enterprise platform.

By extracting pure Java 25 domain models, establishing clear inbound and outbound ports, and wiring pluggable adapters, you reclaim control over your software architecture. Combined with the incremental Strangler Fig migration pattern and automated ArchUnit guardrails, your engineering organization can modernize legacy codebases safely without risking production downtime.

References and Companion Code

• Workshop Companion Code: Refactoring Legacy Spring Boot to Hexagonal Architecture
• Hexagonal Architecture in Spring Boot 4: Hands-On Implementation Guide
• Enforcing Hexagonal Architecture with ArchUnit and Spring Boot
• Modern Local Development: Testcontainers & Docker Compose in Spring Boot 4
• TDD with Spring Boot 4 and Testcontainers: The Zero-Mocking Approach
• Java 25 Virtual Threads: Production Pitfalls and Best Practices for Spring Boot
• Alistair Cockburn’s Original Hexagonal Architecture Specification
• Official Spring Boot Framework Documentation