Contribute to help us improve!

Are there edge cases or problems that we didn't consider? Is there a technical pitfall that we should add? Did we miss a comma in a sentence?

If you have any input for us, we would love to hear from you and appreciate every contribution. Our goal is to learn from projects for projects such that nobody has to reinvent the wheel.

Let's collect our experiences together to make room to explore the novel!

To contribute click on Contribute to this page on the toolbar.

Hexagonal Architecture

Hexagonal architecture, also known as Ports and Adapters, is a software design pattern that promotes separation of concerns by organizing an application into a central core surrounded by external adapters. The core contains the business logic and communicates with the external world via well-defined ports (interfaces). Adapters implement these ports and handle the translation between the core’s domain model and the specific technologies or protocols used by external systems.

devonfw hexagonal architecture blueprint
Figure 1. Hexagonal Architecture Reference
└── application/
    ├── core/
    │   ├── domain/
    │   │   ├──
    │   │   ├──
    │   │   ├──
    │   │   └──
    │   ├── ports/
    │   │   ├── in/
    │   │   │   ├──
    │   │   │   ├──
    │   │   │   ├──
    │   │   │   ├──
    │   │   │   └──
    │   │   └── out/
    │   │       └──
    │   ├── usecase/
    │   │   ├──
    │   │   ├──
    │   │   └──
    │   └── [service]/
    │       └── []
    └── adapter/
        ├── in/
        │   └── rest/
        │       ├──
        │       ├── model/
        │       │   └──
        │       └── mapper/
        │           └──
        └── out/
            └── jpa/
                ├── model/
                │   ├──
                │   └──
                └── mapper/
Package Description


The core contains the essential business logic, domain entities, and use cases. It focuses on implementing the main functionalities while remaining technology-agnostic. The core interacts with external components through well-defined interfaces called "ports," ensuring a clear separation of concerns and promoting flexibility, testability, and maintainability.


The domain package contains the entities and value objects of the business domain of the application. Related Factories or Builders are located here as well. It’s proposed to make entities anemic. See Anemic vs Rich domain models


Use Cases are the main entrypoint of the applications core. They validate the given input and orchestrate the domain entities, services and ports to implement a Business Use Case. Usually a use case implementation should only include a small dedicated use case. Depending of the size and adjacency of the use cases a grouping might make sense (e.g. ManageTableUc)


Ports are interfaces, that are used by the core and should be implemented by an according adapter. Ports should not be technology specific. One big advantage of the hexagonal architecture is, that the adapters can be changed without changing the core and therefore, without touching the business logic. It needs to be distinguished between incoming ports and outgoing ports.

Incoming ports are the entry of the application. They provide interfaces that are called from incoming adapters and hide the actual implementation. A proposal of structuring incoming ports is naming them like single use cases (e.g. CancelReservationPort). Each port should only provide a single method. .Design Decision [%collapsible] ==== Incoming Ports are not as relevant for the hexagonal architecture as the outgoing ports. Outgoing ports are used for the dependency inversion pattern. For incoming ports could also call the use cases directly. Therefore, an pragmatic alternative would be leaving out the incoming ports.

It was decided to include the incoming ports nonetheless. They should implement single use cases that are offered. Each interface should clearly mark the use case that contains only one method. Use cases from the interface might be grouped logically in the use case implementation class. ====


Outgoing ports are an abstraction of everything in the surrounding context that is actively triggered by the core or used as data sink. This might include other services that are called, files that are written, databases, event streaming and everything the application is actively triggering outside of the core. Outgoing ports should describe the business need for the communication (e.g. StoreReservationPort). How this is then realized depends on the adapter that implements it. This way a technology can be easily replaced. For example storing the reservation could be be realized in a first prototype by writing the objects to a file. Later it could be replaced with a database. The core logic would be untouched by that.

[optional] core.service

Services can be considered as business helper classes. They provide a reusable part of the applications business logic that is used by multiple use cases or that helps to structure the application in a logical way. Services are optional as they can be used, when there’s a real need. Usually a use case should contain the business logic.


Adapters connect the application core to the surrounding context. They have the following tasks:

  • Implement a specific protocol to connect to the context. E.g REST, JDBC, MQTT, …​

  • Maintain a data model that is necessary to communicate with the context

  • Translate the domain model from the core to that model or vice versa

  • Handle protocol specific errors

  • Log the interaction with the surrounding context

Incoming adapters specify connection points for everything that can trigger the business logic. That might be interfaces (HTML, RPC, etc), Message Consumers or schedulers for batch processing. Inside the adapters further packages are differentiating the category of the adapter (e.g. .web).


Outgoing adapters define outgoing connections where the application actively interacts with context outside. That can be database connections, file operations, API calls, message producing and many more. Inside the adapters further packages are differentiating the category of the adapter (e.g. .repository).

Anemic vs Rich domain models

"In a rich domain model, as much of the domain logic as possible is implemented within the entities at the core of the application. The entities provide methods to change state and only allow changes that are valid according to the business rules. […​] In an “anemic” domain model, the entities themselves are very thin. They usually only provide fields to hold." [Hombergs21]

Considering java as an object oriented language it feels natural to implement business logic inside the entities themselves. In large scale application we propose to not use rich domain models. There are two reasons for this:

  1. the domain objects are returned to the adapters. If they include business logic this is revealed and available outside of the core, which should not be the case. The answer to this problem could be an additional mapping, but this leads to a lot of unpractical mappings.

  2. adding the business logic to the domain entities spreads it across use cases, entities and services. This makes the application more difficult to understand and harder to locate the place for new features or changes.

Therefore, we propose to implement the domain model as anemic entities and make usage of use cases and services to implement the business logic and interact with the domain models.


  • [Hombergs21] Tom Hombergs. Get Your Hands Dirty on Clean Architecture. 2021.