Hexagonal Architecture — Ghost Order: Adapter Transaction

Every codebase eventually hits the same wall: the business logic is so tangled up with database calls, HTTP frameworks, and third-party SDKs that changing one thing breaks three others. A sprint that should take a day takes a week because your OrderService knows about Hibernate annotations, Spring's @Autowired, and Stripe's API all at once. This isn't a skill problem — it's an architecture problem, and it's exactly the pain that Alistair Cockburn designed Hexagonal Architecture to eliminate in 2005.

The core idea is radical in its simplicity: your application should have no knowledge of the outside world. It shouldn't know whether it's being called by an HTTP request, a CLI command, or a test suite. It shouldn't know whether it's persisting data to PostgreSQL, a flat file, or an in-memory map. All that external detail is pushed behind interfaces — called Ports — and concrete implementations of those interfaces — called Adapters — live entirely outside the application's core domain. The result is a domain model that's pure business logic, nothing else.

By the end of this article you'll understand how to decompose a real feature (an e-commerce order placement flow) into a proper Hexagonal Architecture using Java, why the distinction between Driving (Primary) and Driven (Secondary) adapters matters for testing, how to handle production gotchas like transaction boundaries that cut across adapter layers, and what the honest performance trade-offs are. You'll be able to apply this pattern from day one on a new service and refactor an existing one without a full rewrite.

Core Concept: Ports Are Contracts, Not Implementation Hints

A Port is a Java interface that lives in the core domain package, typically under io.thecodeforge.core.port. It defines what the core needs from the outside world (driven port) or what the outside world can ask the core to do (driving port). The key rule is: the port interface must be expressed in the language of the domain, not in the language of infrastructure.

For example, a SaveOrderPort driven interface should have a method like OrderId save(Order order) rather than void insertIntoOrderTable(OrderRow row). The core shouldn't know about tables, SQL, or even that the data is persisted. This pure abstraction is what makes swapping adapters trivial.

package io.thecodeforge.core.port.driven;

import io.thecodeforge.core.domain.Order;
import io.thecodeforge.core.domain.OrderId;

/**
 * Driven port: the core tells the outside world to save an order.
 * The adapter decides how (DB, file, queue, etc.).
 */
public interface SaveOrderPort {
    OrderId save(Order order);
    void delete(OrderId orderId);
}

Driving vs Driven Adapters — The Primary/Secondary Split

Adapters come in two flavours, and the distinction matters for testing, packaging, and debugging.

Driving (Primary) Adapters: Initiate calls into the core. They are the entry points — HTTP controllers, CLI commands, queue listeners, scheduled tasks. They translate external messages into domain commands. In testing, you replace them with your test code (or mock the HTTP layer).

Driven (Secondary) Adapters: Called by the core to perform side effects. They are the exit points — database repositories, REST client proxies, message producers. The core doesn't know about them directly; it only knows the port interface. In testing, you mock or stub the port, never the adapter.

The rule of thumb: driving adapters push calls into the core; driven adapters are pulled by the core.

package io.thecodeforge.adapter.driven.persistence;

import io.thecodeforge.core.domain.Order;
import io.thecodeforge.core.domain.OrderId;
import io.thecodeforge.core.port.driven.SaveOrderPort;
import org.springframework.stereotype.Repository;

/**
 * Driven adapter: implements SaveOrderPort using Spring Data JPA.
 * The core knows nothing about JPA, EntityManager, or transactions.
 */
@Repository
public class OrderRepositoryAdapter implements SaveOrderPort {

    private final SpringDataOrderRepository jpaRepo;

    public OrderRepositoryAdapter(SpringDataOrderRepository jpaRepo) {
        this.jpaRepo = jpaRepo;
    }

    @Override
    public OrderId save(Order order) {
        OrderEntity entity = OrderEntity.fromDomain(order);
        OrderEntity saved = jpaRepo.save(entity);
        return saved.getId();
    }

    @Override
    public void delete(OrderId orderId) {
        jpaRepo.deleteById(orderId.value());
    }
}

Dependency Inversion in Practice — The Real Power of Hexagonal

Hexagonal Architecture is a concrete application of the Dependency Inversion Principle (DIP): high-level modules should not depend on low-level modules; both should depend on abstractions. In Hexagonal terms, the core domain defines the abstractions (ports), and adapter modules implement them. The core has no compile-time dependency on any adapter. This means you can develop, test, and deploy the core independently of infrastructure.

To achieve this in Java, use constructor injection. The core's service classes depend only on port interfaces. A configuration class or a dependency injection container (like Spring) wires the adapters at runtime. This wiring layer is itself an adapter — often called the 'Application Configuration' or 'System Assembly' adapter.

package io.thecodeforge.core.application;

import io.thecodeforge.core.domain.Order;
import io.thecodeforge.core.domain.OrderId;
import io.thecodeforge.core.port.driven.SaveOrderPort;
import io.thecodeforge.core.port.driven.NotifyCustomerPort;
import io.thecodeforge.core.port.driving.CreateOrderUseCase;

/**
 * Core service — depends only on ports, never on adapters.
 */
public class OrderService implements CreateOrderUseCase {

    private final SaveOrderPort saveOrder;
    private final NotifyCustomerPort notify;

    public OrderService(SaveOrderPort saveOrder, NotifyCustomerPort notify) {
        this.saveOrder = saveOrder;
        this.notify = notify;
    }

    @Override
    public OrderId createOrder(Order order) {
        // Business logic: validate, calculate totals, apply discounts
        order.validate();
        order.applyDiscounts();
        
        OrderId id = saveOrder.save(order);
        notify.orderCreated(order.getCustomerEmail(), id);
        return id;
    }
}

Testing Hexagonal Systems — Where the Pattern Shines

One of the biggest wins of Hexagonal Architecture is testability. Because the core depends only on interfaces, you can unit-test all business logic with mocks or in-memory adapters — no database, no network, no startup time. For integration tests, you test each adapter independently against a real resource, using testcontainers or in-memory variants.

package io.thecodeforge.test.core;

import io.thecodeforge.core.application.OrderService;
import io.thecodeforge.core.domain.Order;
import io.thecodeforge.core.port.driven.SaveOrderPort;
import io.thecodeforge.core.port.driven.NotifyCustomerPort;
import org.junit.jupiter.api.Test;
import static org.mockito.Mockito.*;

class OrderServiceTest {

    @Test
    void shouldSaveOrderAndNotifyOnCreation() {
        SaveOrderPort saveOrder = mock(SaveOrderPort.class);
        NotifyCustomerPort notify = mock(NotifyCustomerPort.class);
        OrderService service = new OrderService(saveOrder, notify);

        Order order = new Order("customer@example.com", 100.00);
        service.createOrder(order);

        verify(saveOrder).save(order);
        verify(notify).orderCreated("customer@example.com", order.getId());
    }
}

Production Gotchas: Transactions, Logging, and Circuit Breakers

Real production use reveals several pitfalls that are easy to miss in tutorials. Three of the most common:

1. Transaction boundaries crossing adapters: As shown in the production incident, a @Transactional in the service only covers the database adapter. If a driven adapter calls an external API, the API call is outside the transaction. If the API fails after the DB commit, you have an inconsistent state. Use the Outbox pattern or Saga pattern.
2. Logging in the core: Logging is a cross-cutting concern. Don't make the core depend on SLF4J or Log4j directly. Use a port like LogPort with an adapter that logs. But most teams accept SLF4J as a standard interface and include it in the core — it's a pragmatic trade-off.
3. Circuit breakers in adapters: A driven adapter that calls an external API should implement retry and circuit-breaking. Do this inside the adapter, not the core. The core doesn't know about retries; it just calls the port and expects success or gets an exception.

package io.thecodeforge.adapter.driven.notification;

import io.thecodeforge.core.domain.OrderId;
import io.thecodeforge.core.port.driven.NotifyCustomerPort;
import io.github.resilience4j.circuitbreaker.CircuitBreaker;
import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig;
import org.springframework.stereotype.Service;

@Service
public class EmailNotificationAdapter implements NotifyCustomerPort {

    private final EmailClient emailClient;
    private final CircuitBreaker circuitBreaker;

    public EmailNotificationAdapter(EmailClient emailClient) {
        this.emailClient = emailClient;
        this.circuitBreaker = CircuitBreaker.of("emailService", 
            CircuitBreakerConfig.custom()
                .failureRateThreshold(50)
                .waitDurationInOpenState(Duration.ofSeconds(30))
                .build());
    }

    @Override
    public void orderCreated(String email, OrderId orderId) {
        Supplier<Void> decorated = CircuitBreaker.decorateSupplier(circuitBreaker, 
            () -> { emailClient.send(email, "Order " + orderId + " confirmed"); return null; });
        Try<Void> result = Try.ofSupplier(decorated);
        result.onFailure(throwable -> log.warn("Failed to send email for order {}", orderId, throwable));
    }
}

Frequently Asked Questions