Most software eventually becomes a tangled mess where changing the database means rewriting half the application. Business rules get buried under layers of framework-specific code. Testing requires spinning up entire infrastructures just to verify that a discount calculation works correctly.

Hexagonal architecture—also called ports and adapters—offers a different approach. It draws a clear boundary around your business logic, treating everything outside that boundary as interchangeable implementation details. Your domain doesn't know or care whether data comes from PostgreSQL, MongoDB, or a spreadsheet.

This isn't just architectural aesthetics. When your core business rules remain independent of technical choices, you gain the freedom to evolve infrastructure without surgery on the parts that actually matter. You can test domain logic in milliseconds, swap out vendors without panic, and reason about what your system does separately from how it connects to the world.

The hexagonal model divides your system into two distinct regions. The inside contains your application core—the business rules, domain logic, and policies that define what your software actually does. The outside contains everything else: databases, web frameworks, message queues, third-party APIs, and user interfaces.

This boundary isn't arbitrary. The inside represents decisions that change when the business changes. The outside represents decisions that change when technology changes. A new pricing algorithm affects the inside. Migrating from MySQL to PostgreSQL affects only the outside.

The critical discipline is ensuring the inside never depends on the outside. Your order calculation shouldn't import anything from your HTTP framework. Your inventory rules shouldn't reference specific database column names. Dependencies flow inward—adapters depend on the core, never the reverse.

Many codebases get this backwards. Business logic spreads across controllers, repositories, and framework hooks. When you need to change the web framework, you discover that order validation logic lives in a controller. When you switch databases, you find that pricing calculations reference specific query syntax. The hexagonal boundary prevents this contamination by making the dependency direction explicit and enforced.

Takeaway

The most valuable code in your system—your business logic—should be the code that knows the least about how it gets called or where data comes from.

Ports are the interfaces that define how the outside world interacts with your application core. They express what the application needs without specifying how those needs get fulfilled. A port might declare that the system needs to persist orders, notify customers, or check inventory—all without mentioning specific technologies.

Inbound ports define the operations your application offers. They represent use cases: CreateOrder, ApplyDiscount, GenerateReport. These interfaces use domain language, not technical language. Parameters and return types are domain objects, not HTTP requests or database rows.

Outbound ports define what your application needs from the external world. They're interfaces for dependencies the core requires but doesn't implement: OrderRepository, NotificationService, PaymentGateway. The core codes against these abstractions without knowing whether the repository talks to PostgreSQL, DynamoDB, or an in-memory collection.

The art lies in designing ports at the right level of abstraction. Too specific, and you're just wrapping technical APIs. Too generic, and you lose meaningful contracts. A good port expresses a genuine application need—'find orders by customer' rather than 'execute SQL query'—while remaining precise enough to guide implementation. The port should make sense to someone who understands the business domain, even if they don't know your technology stack.

Takeaway

A well-designed port answers the question 'what does the application need?' without answering 'how will that need be met?'

Adapters are the concrete implementations that bridge ports to specific technologies. They translate between the domain concepts your core understands and the technical realities of databases, APIs, and user interfaces. Each adapter knows about one specific technology and one port—nothing else.

Inbound adapters receive external requests and translate them into domain operations. An HTTP controller is an inbound adapter: it parses JSON, validates request structure, converts data into domain objects, calls the appropriate port, and transforms the result back to HTTP responses. A message queue consumer is another inbound adapter performing the same translation for asynchronous messages.

Outbound adapters implement the interfaces your core needs. A PostgreSQL repository adapter implements OrderRepository by translating domain queries into SQL, executing them, and converting results back to domain objects. A Stripe adapter implements PaymentGateway by translating payment requests into Stripe API calls.

The key insight is that adapters are disposable. When you switch from PostgreSQL to MongoDB, you write a new adapter implementing the same port. The core remains untouched. When you add a GraphQL API alongside REST, you write a new inbound adapter calling the same use cases. Adapters contain all the messy technology-specific code, quarantined from business logic. Testing the core means injecting fake adapters that implement the ports with in-memory collections and recorded interactions—fast, deterministic, and independent of external systems.

Takeaway

Adapters are translation layers that absorb technology complexity, keeping your core clean and making infrastructure decisions reversible.

Hexagonal architecture isn't about adding layers for their own sake. It's about making one crucial distinction: separating the code that defines what your system does from the code that connects it to specific technologies.

When you maintain this boundary, you gain options. Testing becomes fast and reliable. Technology migrations become manageable projects rather than existential threats. New team members can understand business rules without learning your entire infrastructure stack.

The hexagon shape itself doesn't matter—the original name emphasized that there's no magic number of ports. What matters is the discipline of dependency direction: the core depends on nothing external, and everything external depends on the core. That simple rule, consistently applied, transforms how software evolves.