Hexagonal Architecture (Ports & Adapters)

The problem

In a layered app the business logic imports the database driver. Testing a pricing rule then needs a live DB, and switching from REST to a queue consumer means touching the core. The core should not know how it's called or where data lives.

How it works

• Ports are interfaces owned by the core. Inbound ports are use cases. Outbound ports are what the core needs, such as a repository or a publisher.
• Adapters implement the ports for a specific technology.
• Dependencies always point inward. The core imports nothing from the adapters.

// Port (owned by the core)
export interface ReleaseRepository {
  findById(id: string): Promise<Release | null>;
  save(r: Release): Promise<void>;
}
// Adapter (infrastructure)
export class MongoReleaseRepository implements ReleaseRepository { /* driver code */ }
// Test adapter
export class InMemoryReleaseRepository implements ReleaseRepository { /* Map-based */ }

Trade-offs

• ✅ The core is testable with in-memory adapters, so tests run in milliseconds.
• ✅ Infrastructure can be swapped without touching business code.
• ❌ More files and indirection. Over-abstracted, it becomes "interface for everything".
• ❌ Needs discipline in code review. Imports leak inward easily.

In one line

Hexagonal means the domain owns interfaces for everything it needs, and infrastructure plugs in as adapters. I use it where the rules are valuable enough to deserve fast, DB-free tests.