Definition: Architectural pattern that isolates business logic from the outside world through ports and adapters, improving testability and enabling technology changes.
— Source: NERVICO, Product Development Consultancy
What is Hexagonal Architecture
Hexagonal architecture, also known as the ports and adapters pattern, is an architectural style proposed by Alistair Cockburn. Its fundamental principle is that business logic (the application core) should not depend on any external detail: not the database, not the web framework, not third-party services. Communication between the core and the outside world happens exclusively through ports (interfaces) and adapters (concrete implementations).
How it works
The application core defines input ports (use cases the application exposes) and output ports (interfaces the application needs to function). Adapters connect these ports to concrete technologies. An input adapter can be a REST controller or a message handler. An output adapter can be a PostgreSQL repository or an HTTP client. The core never directly imports or references these implementations.
Why it matters
When business logic is decoupled from infrastructure, changing the database, framework, or service provider does not require modifying business rules. Unit tests run without real infrastructure because output ports are replaced with mocks. This decoupling reduces long-term maintenance cost and makes system evolution easier.
Practical example
A billing service has its business logic in the core: calculating taxes, applying discounts, generating invoices. The output port “InvoiceRepository” defines what operations are needed. Initially, the adapter implements that port with MongoDB. When the team decides to migrate to PostgreSQL, they only replace the adapter. The business logic, representing 70% of the code, does not change a single line.