Ports and Adapters Architecture

Ports and Adapters or also known as Hexagonal Architecture, is a popular architecture invented by Alistair Cockburn in 2005.

Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases. Alistair Cockburn

The idea of Ports and Adapters is that the application is central to your system. All the inputs and outputs reach or leave the core of the application through a port. This port isolates the application from external technologies, tools and delivery mechanics.

The application itself should never have any knowledge about who is sending or receiving the input and output. This allows the system to be secured against the evolution of technology and business requirements. You don’t want that an external system you use, to become obsolete. And then be completely coupled to it. You wan’t to be free from these changes, and make it easy to switch technologies or business partners.

What is a Port?

You can see a port like a gateway. It allows the entry or exiting of data to and from the application. In code, this is what we call an interface.

Ports exist in 2 types. You have the inbound and outbound ports.

An inbound port defines the exposure of the core’s functionality. These interfaces define how the Core Business Logic can be used. This is the only part of the core exposed to the outside world.

An outbound port define the core’s view of the outside world. This are the interface the core need to communicate with the outside world.

What is an Adapter?

In short, the adapter transform an interface into another.

You need to understand that there are 2 kind of adapters. Based on this the transformation itself is different.

Primary Adapters

The primary or Driving Adapters represents the UI. This can be our API controllers, Web controllers and views. They are called driving adapters because they drive the application, and start actions in the core application. These adapters can use the inbound ports (interfaces) provided by the core application. The controllers then depends on these interfaces of the core business logic.

Secondary Adapters

The secondary or Driven Adapters represent the connection to your back-end databases, external libraries, mail API’s, etc. These adapters react to actions iniated by the primary adapters. The secondary adapters are implementations of the outbound port. Which in return depend on interfaces of these external libraries and tools to transform them, so the core application can use these without being coupled to them.


The goal of Ports and Adapters is to isolate the business logic from the delivery mechanics and tools used by the system. For this we use Interfaces. All dependencies are in the direction of the core application. The core itself does not depend on anything.

We create adapters on the UI side of our application to use our applications interfaces. And on the infrastructure side we create adapters that implement our application’s interfaces.

The application core itself can be constructed using a Layered Architecture. Most of the time you will see both these architectures combined, and then just be called Hexagonal Architecture.

We then have a systems that is completely isolated from external changes and any framework you use. Off course in reality it will not be that easy to switch frameworks, but at least we are not fully dependent on it.

This is why it’s a good idea to use this approach of ports and adapters in your applications when thinkering about the architecture.

But be aware. It’s not always a good idea to just use an architecture like this on a simple an basic application. It’s better to know about the ideas behind different architecture’s and then use these ideas that make sense for your situation. As always, think before you code!