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.

Why Hexagonal Architecture Is About Boundaries, Not Layers

Hexagonal architecture, also known as ports and adapters, decouples the core business logic from external concerns — databases, APIs, UIs, message queues — by defining explicit ports (interfaces) inside the core and adapters outside that implement them. The core never imports an external library or framework; it only depends on its own ports. This inverts the traditional layered architecture: instead of the core calling the database, the database adapter implements a port the core defines.

In practice, each external system gets its own adapter — one for Postgres, one for a REST API, one for an in-memory store — all conforming to the same port. You can swap adapters without touching core code. The core remains testable in isolation: mock the port, verify behavior. No Spring context, no database connection, no HTTP server needed for unit tests. The hexagonal shape is a visual metaphor: the core is the hexagon, each side is a port, and adapters plug into those sides.

Use hexagonal architecture when your system must survive changes in infrastructure — swapping databases, adding new API consumers, or migrating from monolith to microservices. It shines in domains where business rules are complex and long-lived, and where external integrations are volatile. The cost is indirection: you write an interface and an adapter for every external interaction. The payoff is that a decade later, when you migrate from Oracle to CockroachDB, you change one adapter, not the entire codebase.

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));
    }
}

Real-World Hexagonal: What Shopify and Netflix Actually Do

Theory is cheap. Let's talk about where this pattern survives production traffic.

Shopify doesn't have a "hexagonal architecture." They have a core domain that processes orders, and that domain talks to payment gateways through contracts. When they add a new payment provider, they write an adapter. The core logic never changes. This isn't about being clever — it's about not rewriting your checkout flow every time Stripe changes their API.

Netflix does the same thing with content delivery. Their recommendation engine doesn't know it's talking to a CDN. It knows it needs to fetch a video stream. Whether that stream comes from Akamai, AWS, or their own Open Connect appliance is irrelevant to the business logic.

The pattern succeeds because it solves a concrete operational problem: external dependencies change. Databases get migrated. APIs get deprecated. If your business logic is tangled with your infrastructure, every external change becomes a rewrite. If it's behind ports, it's a ticket.

This isn't academic. It's survival.

// io.thecodeforge — system-design tutorial

from abc import ABC, abstractmethod

class PaymentPort(ABC):
    @abstractmethod
    def charge(self, amount: Decimal, token: str) -> TransactionResult:
        pass

class StripeAdapter(PaymentPort):
    def charge(self, amount: Decimal, token: str) -> TransactionResult:
        try:
            response = stripe.Charge.create(
                amount=int(amount * 100),
                currency='usd',
                source=token
            )
            return TransactionResult(
                success=True,
                transaction_id=response.id
            )
        except stripe.error.StripeError as e:
            return TransactionResult(
                success=False,
                error_code=e.code
            )

class PayPalAdapter(PaymentPort):
    def charge(self, amount: Decimal, token: str) -> TransactionResult:
        paypal_response = paypalrestsdk.Payment.execute(token)
        return TransactionResult(
            success=paypal_response.success,
            transaction_id=paypal_response.id
        )

The Four Components That Actually Matter (Skip the Yoga Pants Diagrams)

Every blog post draws a hexagon with labels. I'm going to tell you what each piece actually does in production.

Entities — Your business objects with real behavior. Not anemic structs. An Order should know if it can be shipped. A Subscription should validate its own billing cycle. If your entities are just data bags with getters, you've built an ORM wrapper, not a domain.

Ports — Interfaces that define what the domain needs. Not what tech stack can provide. A UserRepository port has methods like find_by_email() and save(). It does NOT have query_raw_sql() or execute_stored_procedure(). The port is the contract. The adapter is the implementation.

Application Services — These orchestrate. They don't contain business rules. A CreateOrderService fetches the user, validates inventory, creates the order, and dispatches events. The business logic lives in the entities, not the services. If your services have if statements about pricing, you've smuggled domain logic into the wrong layer.

Adapters — The ugly infrastructure glue. They translate between your pristine domain and the grimy real world of SQL, HTTP, and message queues. Adapters should be thin. If your adapter has more logic than the entity it serves, you're leaking abstraction.

These four components. That's the architecture. Everything else is ceremony.

// io.thecodeforge — system-design tutorial

class OrderEntity:
    def __init__(self, items: list[OrderItem], status: str):
        self.items = items
        self.status = status

    def can_be_shipped(self) -> bool:
        return (
            self.status == 'confirmed'
            and all(item.in_stock for item in self.items)
        )

class CreateOrderService:
    def __init__(self, user_repo: UserRepository, payment_port: PaymentPort):
        self.user_repo = user_repo
        self.payment_port = payment_port

    def execute(self, user_id: str, items: list[OrderItem]) -> OrderEntity:
        user = self.user_repo.find_by_id(user_id)
        if not user.is_verified:
            raise OrderValidationError("Unverified user cannot create orders")

        order = OrderEntity(items=items, status='pending')
        result = self.payment_port.charge(order.total, user.payment_token)

        if result.success:
            order.status = 'confirmed'
        else:
            order.status = 'failed'

        return order

Why Hexagonal Pays Off: Speed, Safety, and Swap Costs

Hexagonal architecture delivers three measurable benefits. First, test speed. When business logic depends on interfaces instead of databases or HTTP clients, you substitute mocks or in-memory adapters in unit tests — no spinning up Postgres, no network calls. Second, swap cost. The same port (contract) can have a PostgreSQL adapter today and a DynamoDB adapter tomorrow without touching domain code. Changing payment providers? Write one adapter, plug it in. Third, isolation. Adapter failures (timeouts, rate limits) don't cascade into core logic because ports define the contract, and the adapter handles retries. Teams adopting hexagonal report 40-60% faster test suites for domain modules and lower regression risk when swapping infrastructure. The pattern forces you to put boundaries where they belong: at the system edge, not between your business rules.

// io.thecodeforge — system-design tutorial

from abc import ABC, abstractmethod

class PaymentPort(ABC):
    @abstractmethod
    def charge(self, amount: float) -> str: ...

class StripeAdapter(PaymentPort):
    def charge(self, amount: float) -> str:
        return f"Stripe charge ${amount}"

class PayPalAdapter(PaymentPort):
    def charge(self, amount: float) -> str:
        return f"PayPal charge ${amount}"

# Domain never knows which adapter it's using
def checkout(payment: PaymentPort, total: float) -> str:
    return payment.charge(total)

Start with the Port, Not the Framework

Getting started with hexagonal architecture means ignoring the database, web framework, and external APIs — resist that instinct. Step one: write the domain interface (port) that your business logic needs. If you're building an order service, define an OrderRepository port with methods like save(order) and findById(id). Step two: implement a fake adapter in-memory — a dict-backed stub. Step three: write your domain logic against the port, passing the adapter. Verify the logic works with a unit test. Only then write the real adapter (Postgres, Redis). This sequence forces you to think about what the domain actually requires, not what the ORM provides. Common pitfall: starting with Django models or Spring repositories leads to leaky abstractions. The port defines the contract; the adapter is just a driver. Start with a test, a port, and a fake.

// io.thecodeforge — system-design tutorial

from abc import ABC, abstractmethod

class InventoryPort(ABC):
    @abstractmethod
    def reserve(self, sku: str, qty: int) -> bool: ...

class FakeInventoryAdapter(InventoryPort):
    def __init__(self):
        self._stock = {"SKU-123": 10}
    def reserve(self, sku: str, qty: int) -> bool:
        if self._stock.get(sku, 0) >= qty:
            self._stock[sku] -= qty
            return True
        return False

# Domain logic — pure, testable
def create_order(inventory: InventoryPort, sku: str, qty: int) -> str:
    return "confirmed" if inventory.reserve(sku, qty) else "denied"

Overview

Hexagonal Architecture, also called Ports and Adapters, was introduced by Alistair Cockburn in 2005 to solve a fundamental problem: how do we build software that remains decoupled from infrastructure? Traditional layered architectures often leak framework or database concerns into business logic, creating tight coupling that makes testing painful and replacement expensive. The hexagonal pattern inverts this by placing the business domain at the center and expressing all external interactions—databases, APIs, message queues, UIs—through abstract ports. Adapters on the peripheral implement those ports, translating between the outside world and the core. The name comes from the visual metaphor of a hexagon, though the number of sides is arbitrary; the key insight is that the system has multiple, symmetric entry points, not a top-heavy layer stack. This overview sets the stage: hexagonal is about protecting your business rules from change, not about drawing pretty shapes. Every port is a boundary where ownership flips—you control the contract, the adapter handles the how.

// io.thecodeforge — system-design tutorial
// 25 lines max

# Core domain — no database, no HTTP
class Order:
    def __init__(self, id, items):
        self.id = id
        self.items = items
        self.status = "pending"

    def approve(self):
        if not self.items:
            raise ValueError("Empty order cannot be approved")
        self.status = "approved"

# Port (interface)
class OrderRepository:  # abstract port
    def save(self, order): ...
    def find_by_id(self, order_id): ...

Principles

Three principles govern hexagonal architecture. First, Dependency Rule: dependencies point inward. The domain core never imports frameworks, databases, or UI libraries—only plain language abstractions. Second, Port Boundary: a port is a contract defined by the core, not the infrastructure. It specifies what the core needs (e.g., "save this order"), not how the adapter will implement it. Third, Adapter Symmetry: each external actor gets its own adapter. A MySQL adapter implements the OrderRepository port; an HTTP adapter implements the Notifier port. Adapters can be hot-swapped without altering core logic. These principles enable testability—mock the port, test the domain—and change tolerance. When Stripe replaces PayPal, you swap one PaymentPort adapter for another; the approval logic in the core never blinks. The real art: resist the temptation to let the ORM's query patterns dictate your port signatures. Own the contract, own your business rules.

// io.thecodeforge — system-design tutorial
// 25 lines max

from core.ports import OrderRepository, PaymentGateway

class PostgresOrderRepo(OrderRepository):
    def save(self, order):
        # ORM specifics here — core stays clean
        print(f"INSERT INTO orders VALUES ({order.id})")

def confirm_order(order_id, repo, payment):
    order = repo.find_by_id(order_id)
    payment.debit(order.total)
    order.approve()
    repo.save(order)