Hexagonal Architecture and Modular Implementation

README.md

Hexagonal Architecture

Conceptualized by Alistair Cockburn. Also known as "Ports and Adapters".

In a nutshell:

Application Driver -> Primary Adapter -> Primary Port -> Use Case -> Secondary Port -> Secondary Adapter -> External System/Side Effect

Use Cases

They define the business rules and they should not depend on code related on how the system communicates with the outside world. Throught the use of Ports and Adapters the Use Cases can be reliably tested and change mainly if the business rules change

Ports

They expose the ways in which the use cases can be reached (primary) or reach to (secondary) to the outside world. They are technology agnostic.

Adapters

They deal with with side effects such as: communication outside of the system, random generation, current time, etc.

Port and Adapter Implementation

Hexagonal Architecture - Modular Implementation

Based on talks by Jakub Nabrdalik.

Modules Project Structure

There are multiple ways to implement the ideas of this architecture this is by no means the only one. This implementation is modular and as such it can scale to implement a modular monolith (modulith).

• Each module is an Hexagonal Architecture "Hexagon" (It has ports, adapters and use cases).
• There is a heavy use of package-private and a minimal, thoughtful use of public.
• Subjects Under Test in your unit tests are Primary adapters (mocking the Primary Port), the DTOs (if needed) and the Primary Port (using fakes and mocking other modules)
• Each module has a Configuration file that assembles the classes together for production and testing use.

Additional notes on implementation

• In the following example I decided to move customerconsole package outside of the customer module because it required it's own module configuration. However, there is nothing stopping the package to remain as a folder inside of com.abc.project.customer

• Depending on the library choice or code implementation, your primary adapters may need to be public. Jakub's package-private controllers are possible because he uses the Spring framework.

• Primary adapters expose an API to an external agent so you may want to treat them as a public API regardless of the access modifier used for the class

Module configuration and it's relationship with mock testing:

https://gist.github.com/corlaez/aa2c1a657438f5c998af9340a3339051

Useful Links:

• Articles by Alistair Cockburn:

  • Hexagonal Architecture on c2 wiki
  • Ports and Adapters on c2 wiki
  • Hexagonal Architecture on Alistair's webpage

• Talks by Jakub Nabrdalik:

  • "Hexagonal Architecture in practice"
  • "Improving your Test Driven Development in 45 minutes"

• Excalidraw Library used to create the diagrams shown here.

• Implementation examples:

  • Github Java Example by Jakub Nabrdalik (Spring, HTTP API, Repository)
  • Replit Java Example by me (0 libraries, Console, System Time, Random)