Skip to content

Use Hexagonal architecture during platform module development.

Context and Problem Statement

The architecture of a PSS®X service should follow the principle of an onion hexagonal architecture (cf. onion architecture). The inner-most layer defines the service’s genuine business logic abstracted from external dependencies.

The goal is to write the business logic in a way so that it does reduce any technical dependencies so far as possible that might change when using another database or communication method. The business logic is the real intellectual property of an application and is expected to outlive frameworks and/or systems.

The layers wrapping the inner-most layer with the business logic encapsulate concrete details for an external dependency from the business logic. The business logic does not access directly for instance a database but relies on a wrapping layer to implement the necessary operations.

A microservice might use the following layers to implement an onion architecture where layer Domain-core is the inner-most layer, layer Use-cases wraps layer Domain-core, and layer Infrastructure wraps layer Use-cases.

Domain-core: The service genuine business logic. It provides the basic operations the service implements. This layer knows for instance what it wants to achieve in a database but does not care about the details.

Use-cases: A use case implements an action that the user might invoke using the operations provided domain code. A use case typically contains a sequence of domain-core operations. Use cases compose domain-core operations but are still abstract as far as accessing external dependencies are concerned.

Infrastructure: This layer connects business logic and use cases to the concrete environment the application has to work with. This layer provides concrete access to a particular database (i.e., PostgreSQL or MySQL or an OR-mapper) or communication method (i.e., Kafka or RabbitMQ for message queues). It knows how to achieve the operations requested by the business logic.

Note that a use case as defined in a user story for a feature might combine different services and therefore depend on several basic use cases defined in the services layer Use-cases.

Layer Domain-core implements a service’s business logic and the number of direct dependencies between its code and any third-party code should be decreased as far as possible. This makes the core less vulnerable against changes in dependencies.

This does not mean that the business logic may not use libraries but that each dependency has to be considered carefully.

Considered Options

  • Hexagonal architecture
  • Monolith architecture

Decision Outcome

Chosen option: "Hexagonal architecture" because,

  • A microservice’s architecture should have its business logic clearly separated from technical aspects like connecting to a particular database or use a specific encoding for data transmission..

Consequences

  • The business logic is independent from any concrete environment.
  • The business logic is a clearly identified "entity: (e.g., a package).
  • It is easy to test business logic in isolation.
  • It is possible to use a different component (e.g., switch from MySQL to PostgreSQL) without touching the business logic.
  • It is possible to use the business logic in different settings.