Hexagonal Architecture: Why Architecture

Hexagonal architecture is a specific instance of an architecture

pattern. Why do we need one at all?

Make software easier to change

Make software easier to test

Make software easier to reason about

Make software easier to write with fewer bugs

Reduce the future cost of changing your mind later, aboutnearly anything

Michael Nash Hexagonal Architecture

Hexagonal Architecture: DefinitionWhat is Hexagonal Architecture?

An alternative to the “standard layered model”

Developed by Alistair Cockburn

Later called Ports and Adapters

Also called the Onion Architecture

Involves application of the Dependency Inversion Principle

Michael Nash Hexagonal Architecture

Hexagonal Architecture: ContrastWhat is the Standard Layered Model?

UI

Application

Domain

Network and database

Hexagonal architecture rejects the notion that any of these layersexcept the domain are different from one another. E.g. a usersitting at a UI is not much different than a flat file full of testcases, or a network and a database.

Michael Nash Hexagonal Architecture

Layered Architecture: Diagram

Michael Nash Hexagonal Architecture

Hexagonal Architecture: Diagram

Domain on the inside, infrastructure (ports and adapters) on theoutside

Michael Nash Hexagonal Architecture

Hexagonal Architecture: ValueWhy Hexagonal Architecture?

What does this architecture buy us?

Symmetrical

Verifiable – you can tell when you’ve got it by inspection

Decouple core logic (the domain) from infrastructure

Always possible to test everything easily

Infrastructure changes are not relevant to the domain logic

Makes package and module structure consistent and easy tonavigate

Natural fit with DDD and EDA

Language and framework agnostic

Excellent fit with functional programming

Michael Nash Hexagonal Architecture

Hexagonal Architecture: Ports and Adapters

Infrastructure services can easily be replaced with others

Michael Nash Hexagonal Architecture

Dependency Inversion Principle

To apply Hexagonal architecture, we use the dependency inversionprinciple

Specific top-level package structure

Careful management of imports and dependency management

Common classes depend on nothing (no IO, utilities only)

Domain classes depend only on common classes and eachother

Services classes depend on domain, adapt to infrastructure

Infrastructure classes depend on services and domain

Michael Nash Hexagonal Architecture

Dependency Inversion Principle: Diagram

Michael Nash Hexagonal Architecture

Dependency Inversion Principle: Common

The Common package contains only shared utility classes

No I/O!

String utilities

Date utilities

Random numbers

Data structures

NOT what we currently call “common”

Michael Nash Hexagonal Architecture

Dependency Inversion Principle: Domain

The Domain package contains only business domain classes andfunctions

Depends ONLY on other domain classes and common classes

Can use abstractions like logging (traits only)

Contains domain logic – avoid anemic domain!

No I/O

Can contain DDD services for operations that span aggregates

No DTOs

No annotations

Use types, not primitives wherever possible

Michael Nash Hexagonal Architecture

Dependency Inversion Principle: Services

The Services package contains the service classes used by the portsand adapters to interact with the domain

Depends ONLY on domain and common

Expose operations needed by the adapters

No I/O

Could contain Repositories

No event handlers (these are infrastructure)

No REST routing (again, infrastructure)

No DTOs

No annotations

Michael Nash Hexagonal Architecture

Dependency Inversion Principle: Infrastructure

The Infrastructure package contains the adapters that connect theservices and the domain to the outside world

Can depend on any other package as required

Contains sub-packages for specific adapters (e.g. http,eventbus, mongo)

I/O goes here – all of it

Calls services and domain

REST routing goes here

Implementations of repositories go here

DTOs go here

Guice module, dependency injection goes here

Michael Nash Hexagonal Architecture

Hexagonal Architecture: Action Plan

How do we get there? What’s the plan?

Review Hierarchy (now), make sure we all understand thedesired outcome

In other modules, create top-level packages domain, common,services and infrastructure

Refactor into proper package structure, decoupling as required

Decouple from deprecated common modules

Refactor spray-service-common and submodules into re-usableinfrastructure modules

Use Crucible to review and discuss refactors

Specific stories to refactor each module

Decouple EventBus from our domain (make domain-agnostic)

Adopt single-source tree view to facilitate refactorings

Michael Nash Hexagonal Architecture

Hexagonal Architecture: Single Sourcetree View

A single bounded context should be visible as a single logicalsource tree

No more p2build plugin

Refactoring greatly simplified

No more versions of common

Executable artifacts become a deploy-time question: canchange as needed

Acheivable “virtually” right away with git sub-modules(ListingDistributionContext)

Adding new Event types (for example) becomes trivial

One git repo (logically, if not physically at first)

Decouple EventBus from our domain (make domain-agnostic)

Integration tests become trivial (no need to launch multiplejars)

Michael Nash Hexagonal Architecture

Hexagonal Architecture: Conclusion

We want the benefits of hexagonal architecture, hence therefactors

Questions?

Michael Nash Hexagonal Architecture