ADR-005 — Hexagonal Architecture

ADR

ADR-005

Title

Hexagonal Architecture

State

Accepted

Author

klenkes74

Decision Body

klenkes74

Valid from

2025-09-21

Expires

./.

1. Context

Software architecture defines the fundamental structure of a software system, establishing the way components interact and the constraints on their design and evolution. It provides a blueprint for both the system and the project developing it, addressing concerns like scalability, maintainability, and technical debt.

Traditional layered architectures often lead to tight coupling between business logic and infrastructure components (databases, UI, external systems). This creates challenges for testing, maintenance, and adapting to changing requirements. Our system needs an architecture that promotes separation of concerns, testability, and resilience to technical changes.

2. Decision

We will implement Hexagonal Architecture (also known as Ports and Adapters) for our system design.

Key principles of this approach:

  • The core business logic (domain) sits at the center of the application

  • The domain defines "ports" (interfaces) through which it communicates with the outside world

  • External components connect to these ports via "adapters" that translate between the domain and external systems

  • Dependencies point inward toward the domain, never outward

  • The domain has no knowledge of the external systems it interacts with

We will structure our application into three main layers:

  1. Domain Layer: Contains business logic, entities, and use cases

  2. Ports Layer: Defines interfaces for both incoming and outgoing interactions

  3. Adapters Layer: Implements concrete adapters for connecting external systems to the ports

3. Consequences

Adopting Hexagonal Architecture will result in:

3.1. Benefits

  • Testability: The domain can be tested in isolation using mock adapters

  • Flexibility: External components can be replaced without affecting the domain

  • Maintainability: Clear separation of concerns makes the codebase easier to understand

  • Future-proofing: The core business logic is protected from changes in external technologies

  • Domain focus: Developers can focus on business problems rather than technical details

3.2. Challenges

  • Learning curve: Team members will need time to adapt to this architectural style

  • Initial overhead: More interfaces and classes are required compared to simpler approaches

  • Design decisions: Determining proper boundaries between domain and adapters requires careful consideration

  • Potential overengineering: For simpler components, this approach may be unnecessarily complex

4. Further Reading