Hexagonal Architecture: An Introduction Led by DDD

Prashant Tamang — Sun, 11 Oct 2026 06:50:25 +0000

This article is an introduction to hexagonal architecture led by Domain-Driven Design; therefore, we will only cover the basics of DDD to fulfill the prerequisites and learn about hexa in detail.

In domain-driven design (DDD) the core intention is to make the code and business domain complement each other, and for that sake we do some structural architecting. In simpler terms, DDD primarily isolates different parts of the code structure strategically. The separation isn’t just for good readability; it holds a greater purpose. To understand more clearly, let’s set up a hypothetical scenario:

For instance, you are contributing to an ecommerce application (I chose this application as it is the most common and one of the most important applications where DDD shines if implemented correctly). Here, if there is no separation of the context, then there will be one huge context which may contain information about customers, carts, orders, wishlist, operations, logs, and as the app grows, the complexity rises, and eventually a change in one feature affects another feature. Therefore DDD splits the application into bounded contexts, which are boundaries between different features / services in the application. And as we go further inside each context there is more architectural design; we don’t dump the code unsystematically just because the logic belongs to that boundary. We will get to that (how code is managed inside each bounded context) in further sections, but for now, let’s look at another highlighted advantage of DDD: ubiquitous language. When building an application, the business professionals and engineers might not speak the same terms. To clarify: in an order process, for a business professional the steps are generally to place, process, and cancel an order, etc., but for the developers it’s just changing the order status to active, processing, and cancelled. Therefore, for both parties to have a ubiquitous language, the code uses functions named placeOrder(), processOrder() and cancelOrder(); moreover, the business rules are reflected in the function names, and that concludes our DDD exploration.

Now that we have learnt the gist of DDD, we can transition by making a statement that

DDD is a structuring philosophy and hexa is one of the architectural approaches to put this philosophy into practice.

To be clear, they can exist independently of one another. First, let’s understand why it is called hexagonal architecture. It’s obvious that an application might not have exactly six adapters and ports. So why use hexagons? Why not use a heptagon or octagon or a shape with the most possible sides? Well, the simple reason is that the creator of hexagonal architecture (Alistair Cockburn) used a hexagonal diagram to display the idea.

In hexa there are three main components: domain, ports and adapters. The main business logic sits in the domain, and adapters hold the capability to connect the outside world with the domain and complete the tasks using different services the domain asks for. Moreover, ports are interfaces that define how the domain communicates with the outside world, and adapters are the part of the architecture that plug into these ports to connect the outside world with the domain. The domain must not depend on any external factors, not even the framework; it must be just plain code. However, the adapters that are connected through the port should depend on the rules set by the domain and may use external technologies to fulfill the rules.

Now let’s understand ports and adapters architecture (hexagonal architecture) through an interesting example. Let’s assume the database has been changed from PostgreSQL to MariaDB and now it’s your responsibility to connect this new database to your system. If you had a big ball of mud, the migration to a new database system would be a process of rewriting the whole system. In such a case one would only wish for an architecture where they could just change the layer that talks to the database, leaving the other parts untouched. This is one of the many use cases of hexagonal architecture. Similarly, we can visualize the situation where we would need to swap payment methods from one to another, where hexa shines as well. From these scenarios we can conclude that for any part of the architecture where swappability and maintainability are required due to changing requirements (which is inevitable in the working environment), hexa is one of the best options, as it helps to alter the code with minimum restructuring.

Writing unit test cases for an application is a crucial part of development. Without hexa, unit tests often need to mock the database or external service with mocking tools, pretending the server has the required technologies, whereas in hexa you just implement the port interface with a fake adapter which returns the desired output through the port, so no mocking tools or server are required, which completes the testing in a comparatively shorter timeframe.

Now let’s understand driving and driven: they are two sides of an application. On the driving side, the outside world calls the application, for example an HTTP request from clients. On the driven side, the application calls out to the outside world, such as an external DB (e.g., PostgreSQL, MongoDB), and not only databases but also external services such as a third-party payment gateway or a third-party weather API (Application Programming Interface). Now, in terms of code architecture, adapters talk to the application through ports, so there are driving ports/adapters and driven ports/adapters. One of the most important statements is that a driving port is offered by the application, whereas a driven port is required by the application. To make it clearer, PlaceOrderUseCase is a driving port which is offered by the application, and OrderRepository is a driven port which is required by the application.

To answer how code is managed inside each bounded context, we discussed the hexa way and we found a clear answer. In the previous example of DB swapping, if there were randomness with no clear structural path inside the bounded context, performing the swap would still be very hard. And this is where hexa gave the structure to solve the problem. There is an old saying: prevention is better than cure, and here hexa is the prevention. I’ve realized I am being an advocate of DDD and hexa in this article; well, it’s time to switch sides.

There are tradeoffs for implementing hexa, and a few are mentioned below:

Even for simple features, more boilerplate and setup time are required.
If the team doesn’t understand or document the structure properly, people will break the rules and the architecture slowly decays into technical debt.
New developers must learn about every aspect of hexa before they can be productive.

However, if it’s an application you plan to give a long life span and not let it collect dust in your forgotten repositories, you can surely use hexa. On the other hand, if it’s a small application such as a notes app or a todo app, don’t implement hexa just yet, but if you want to learn and implement the architecture, it’s a free world, go ahead.

Conclusion: DDD is a structuring philosophy and hexagonal architecture is an architectural approach. DDD helps us define bounded contexts, whereas hexa makes the architecture swappable, maintainable and easy to test. Generally, long-lived applications benefit from hexagonal architecture, and it’s better to skip it for small applications. The tradeoff of implementing hexa is extra complexity.

DEV Community: Prashant Tamang

Hexagonal Architecture: An Introduction Led by DDD