Why Hexagonal Architecture Is About Ports and Adapters, Not the Hexagon Shape

Many people have heard of Hexagonal Architecture and may even draw a hexagonal diagram, but the core of the architecture is not the shape—it is the ports and adapters that form the architectural soul.

Alistair Cockburn introduced the style in 2005 under the name “Ports and Adapters”. The term “Hexagonal” later became a community nickname because a hexagon provides enough sides to sketch adapters, not because the architecture has six fixed sides.

Ports define the contracts between the core business logic and the outside world, answering “what I need” and “what I provide” without caring about who supplies or consumes them. Adapters are concrete implementations that translate external technical details (SQL, HTTP, JSON) into the language of the core, acting as translators.

The architecture separates the external world into two sides:

Driving side (inbound) : external actors such as browsers, API test scripts, or message producers actively invoke the core. The driving‑side port declares the capabilities the core offers.

Driven side (outbound) : resources like databases, message queues, or third‑party APIs are called by the core. The driven‑side port declares the capabilities the core requires.

Because the core depends only on ports, it is completely technology‑agnostic. You can replace MySQL with PostgreSQL, Spring with Ktor, or Kafka with RabbitMQ without changing any core code. This agnosticism does not mean the core lacks technology; it simply does not know which technology is used.

Ports and adapters are an architectural implementation of the Dependency Inversion Principle (DIP): high‑level modules (the core) depend on abstractions (ports), while low‑level modules (adapters) depend on those abstractions. The Interface Segregation Principle (ISP) also applies—ports should be thin and focused, not “fat” interfaces that force unnecessary dependencies.

Hexagonal Architecture shares the same fundamental idea with Clean Architecture and Onion Architecture—dependencies point inward toward the core. The difference is terminology: Hexagonal emphasizes ports and adapters, Clean emphasizes dependency rules and four layers, and Onion visualizes concentric circles.

Common misreadings addressed in the article:

Misreading: “Hexagonal Architecture is literally six sides.” Correct: The hexagon is only a visual metaphor; the real essence is ports and adapters. ( Cockburn 2005 )

Misreading: “A port is the same as an interface.” Correct: A port is an architectural contract; an interface is a language‑level construct that can implement a port. One port may map to multiple interfaces. ( Cockburn 2005, community consensus )

Misreading: “Hexagonal and Clean are completely different architectures.” Correct: They share the same core principle of inward‑pointing dependencies, differing only in expression. ( Martin 2012 blog; Cockburn 2005 )

Misreading: “All business logic must reside in the core.” Correct: Core holds pure business rules, but infrastructure concerns such as logging, caching, or serialization can live in adapters. ( Cockburn 2005, community consensus )

In summary, Hexagonal Architecture does not claim to be a silver bullet, but it provides a clear constraint: the core should not know the details of the outside world, ensuring business logic remains independent of any specific framework or technology.