Hexagonal and Clean Architecture: Ports, Adapters, and Dependency Inversion

Why These Architectures?

Frameworks, databases, queues, and UI layers change. Core business rules should change because the business changes, not because a web framework or database driver changed.

Hexagonal architecture, onion architecture, and clean architecture all push the same principle: protect the domain and application logic from infrastructure details.

The Core Problem

In many applications, business logic is tangled with controllers, ORM models, queue consumers, and external APIs.

This makes the system hard to test and hard to change. A simple business rule may require a database, HTTP request, framework boot, and third-party client just to run a unit test.

Hexagonal Architecture

Hexagonal architecture is also called ports and adapters. The application core defines ports. Adapters implement those ports for specific technologies.

Ports

A port is an interface that expresses what the core needs or offers.

Adapters

An adapter connects a technology to a port.

Dependency Inversion

Dependency inversion means high-level policy should not depend on low-level details. Both should depend on abstractions.

The core owns the interface because the core decides what it needs. The adapter conforms to that interface.

// Core layer
export interface PaymentGateway {
  authorizePayment(input: {
    orderId: string;
    amount: number;
    currency: string;
  }): Promise<{ authorizationId: string }>;
}

export class PlaceOrderUseCase {
  constructor(private readonly paymentGateway: PaymentGateway) {}

  async execute(command: PlaceOrderCommand) {
    const authorization = await this.paymentGateway.authorizePayment({
      orderId: command.orderId,
      amount: command.totalAmount,
      currency: command.currency,
    });

    return authorization.authorizationId;
  }
}

// Infrastructure layer
export class StripePaymentGateway implements PaymentGateway {
  async authorizePayment(input: {
    orderId: string;
    amount: number;
    currency: string;
  }) {
    const response = await stripe.paymentIntents.create({
      amount: input.amount,
      currency: input.currency,
      metadata: { orderId: input.orderId },
    });

    return { authorizationId: response.id };
  }
}

Clean Architecture Layers

Clean architecture expresses the same dependency rule with concentric layers.

The rule is simple: source code dependencies point inward.

Onion Architecture

Onion architecture is similar, but often emphasizes the domain model at the center and infrastructure on the outside.

The differences matter less than the dependency rule.

Example: Place Order

Responsibilities

Testing Benefits

Because the core depends on interfaces, it can be tested with fakes.

class FakePaymentGateway implements PaymentGateway {
  async authorizePayment() {
    return { authorizationId: "auth-test-1" };
  }
}

class InMemoryOrderRepository implements OrderRepository {
  private orders = new Map<string, Order>();

  async save(order: Order) {
    this.orders.set(order.id, order);
  }
}

Folder Structure

One possible structure:

src/
  domain/
    order.ts
    money.ts
  application/
    ports/
      order-repository.ts
      payment-gateway.ts
    use-cases/
      place-order.ts
  infrastructure/
    database/
      postgres-order-repository.ts
    payments/
      stripe-payment-gateway.ts
  interfaces/
    http/
      order-controller.ts
    queue/
      order-command-consumer.ts

This is a starting point, not a law. The important part is dependency direction, not folder names.

Common Mistakes

When to Use It

Good Boundaries for Ports

Create ports around things that are slow, external, nondeterministic, or likely to vary:

• Database access
• Payment providers
• Email and SMS
• Search engines
• Message brokers
• Object storage
• Clock and ID generation

What to Remember for Interviews

1. Business logic belongs in the core: Frameworks and databases sit outside it.
2. Ports are interfaces owned by the application: Adapters implement them.
3. Dependencies point inward: Outer layers depend on inner layers, not the reverse.
4. Testing improves because the core is isolated: Use fakes for ports and integration tests for adapters.
5. Use pragmatically: The pattern is valuable when complexity, change, or testing pain justifies it.