![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur-layer-1024x1024.png\" "\\"hexagonal_architecture-layer\\"")
<\/figure>\n\n\n\nThe widely used layered architecture, with its three-tier division into presentation, business logic, and data access, often leads to problems in larger projects:<\/p>\n\n\n\n
- \n
- Technical dependencies permeate all layers:<\/strong> If the business logic accesses the data access layer directly, dependencies on technical details arise that affect the business logic. This often becomes apparent when database models are used directly within the business logic. These models are usually designed according to the specifications of the persistence layer\u2014for example, due to requirements from frameworks such as JPA or Hibernate, which enforce public getters and setters. As a result, business invariants can be undermined, and the logic becomes unnecessarily tied to specific database technologies.<\/li>\n\n\n\n
- Layer boundaries are becoming less distinct:<\/strong> When under time pressure, developers tend to blur the boundaries between the layers. As a result, business logic may end up in the presentation layer, or technical details may find their way into the business logic. As a result, the business logic code becomes increasingly difficult to understand; important aspects are harder to identify and can easily be lost during technical adjustments.<\/li>\n\n\n\n
- Testability suffers:<\/strong> Business logic cannot be tested in isolation without technical dependencies such as databases.<\/li>\n<\/ul>\n\n\n\n
The Hexagonal Principle: Business Logic at the Center<\/h2>\n\n\n\n
The hexagonal architecture addresses precisely these weaknesses and flips the perspective: the business logic takes center stage, not the data. All technical details are abstracted to the outside via defined interfaces\u2014known as ports\u2014and implemented using adapters. Ports are part of the business logic and are therefore also given business-specific names.<\/p>\n\n\n\n
The core idea: The application defines what it needs (ports), but not how it is implemented (adapters). This results in clear dependency directions: All dependencies point inward toward the application core. To make this principle more tangible, a distinction is made between primary and secondary ports\u2014depending on whether the application is being controlled or is itself controlling other systems.<\/p>\n\n\n\n
![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur-grafik001-1024x718.png\" "\\"hexagonal_architecture-graphic001\\"\/")
<\/figure>\n\n\n\nApplication<\/h3>\n\n\n\n
In practice, this means that the business logic exposes its use cases via primary ports and uses secondary ports to connect to external systems, such as databases or payment services. In doing so, it remains completely free of technical dependencies.<\/p>\n\n\n\n
![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur-grafik002.png-1024x718.png\" "\\"hexagonale_architektur-grafik002.png\\"")
<\/figure>\n\n\n\nExample 1:<\/strong><\/p>\n\n\n\n
\/\/ prim\u00e4rer Port\ninterface UserRegistrationUseCase {\n fun registerUser(user: User): User\n}\n\/\/ sekund\u00e4re Ports\ninterface UserRepository {\n fun add(user: User): User\n fun existsByEmail(email: String): Boolean\n}\ninterface UserNotificationService {\n fun sendWelcomeMessage(user: User)\n}\n\/\/ Gesch\u00e4ftslogik\ndata class User(\n private val id: String,\n private val name: String,\n private val email: String\n) {\n companion object {\n fun create(name: String, email: String): Appointment {\n require(!name.isBlank(), \u201ename must not be blank\u201c)\n require(isMailAddress(email), \u201eemail must be a valid mail adress\u201c)\n return User(UUID.randomUUID().toString(), name, email)\n }\n }\n}\nclass UserRegistrationService(\n private val userRepository: UserRepository,\n private val userNotificationService: UserNotificationService\n) : UserRegistrationUseCase {\n\n override fun registerUser(user: User): User {\n check(!userRepository.existsByEmail(user.email), \"user with that email is already registered\") \n val newUser = userRepository.add(user)\n userNotificationService.sendWelcomeMessage(newUser)\n return newUser\n }\n}<\/code><\/pre>\n\n\n\nAdapters \u2013 Interfaces to the Outside World<\/h3>\n\n\n\n
Adapters technically implement the previously defined ports. They translate the business logic interfaces into specific technologies\u2014such as REST controllers, database access, or integrations with external services. This ensures that the business logic itself remains unchanged, even if the infrastructure or the frameworks used change over time.<\/p>\n\n\n\n
Primary Adapters \u2013 Controlling the Application<\/h4>\n\n\n\n
Primary adapters, or driving adapters, provide the technical connection to the application. They control the respective use case by calling the corresponding primary ports.<\/p>\n\n\n\n
A REST controller, acting as the primary adapter, translates HTTP requests into business operations:<\/p>\n\n\n\n
![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur_bild03-1024x718.png\" "\\"hexagonal_architecture_image03\\"")
<\/figure>\n\n\n\nExample 2:<\/strong><\/p>\n\n\n\n
@RestController\n@RequestMapping(\"\/api\/users\")\nclass UserRegistrationController(\n private val userRegistrationUseCase: UserRegistrationUseCase\n) {\n\n @PostMapping(\"\/register\")\n fun registerUser(@RequestBody request: UserRegistrationRequest): ResponseEntity {\n try {\n userRegistrationUseCase.registerUser(request.toDomain())\n return ResponseEntity.ok()\n } catch (Exception e) {\n return ResponseEntity.badRequest().body(createErrorResponse(e))\n }\n }\n}<\/code><\/pre>\n\n\n\nSecondary Adapters \u2013 Connecting the Infrastructure<\/h4>\n\n\n\n
This is where the Dependency Inversion Principle comes into play: The business logic defines the interface through secondary ports, and the infrastructure implements it using a secondary adapter. As a result, the business logic remains independent of specific technologies and can continue to function even if external systems or frameworks change.<\/p>\n\n\n\n
![\"\"](\"https:\/\/test.itsonix.eu\/wp-content\/uploads\/2026\/05\/hexagonale_architektur-grafik04.png-scaled.png\" "\\"hexagonale_architektur-grafik04.png\\"\/")
<\/figure>\n\n\n\nExample 3:<\/strong><\/p>\n\n\n\n
class JpaUserRepository(\n private val springDataUserRepository: SpringDataUserRepository\n) : UserRepository {\n\n override fun add(user: User): User {\n val entity = mapToEntity(user)\n val savedEntity = springDataUserRepository.save(entity)\n return savedEntity.toDomain()\n }\n\n override fun existsByEmail(email: String): Boolean {\n return springDataUserRepository.existsByEmail(email) \n }\n}<\/code><\/pre>\n\n\n\nMapping Between Layers \u2013 A Conscious Decision<\/h3>\n\n\n\n
A key aspect of hexagonal architecture is the mapping between domain objects and infrastructure objects.<\/p>\n\n\n\n
- \n
- Domain Objects<\/strong> represent the business logic\u2014that is, concepts and rules from the application domain, such as \"Order\" or \"Invoice.\" They do not include technical details.<\/li>\n\n\n\n
- Infrastructure Assets<\/strong> (or adapter models), on the other hand, are tailored to frameworks or external systems, such as database entities or DTOs for a REST API.<\/li>\n<\/ul>\n\n\n\n
Even though this mapping may seem like extra work at first, it offers significant advantages:<\/p>\n\n\n\n
- \n
- Technical details are left out:<\/strong> Annotations for, e.g., the Validation API, JSON serialization, JPA, and other framework-specific details are present only in the adapter models and do not affect the business logic models.<\/li>\n\n\n\n
- Flexibility in Technology Transitions:<\/strong> Switching from, for example, REST to a message bus requires changes only in the adapter.<\/li>\n\n\n\n
- Clear Data Contracts:<\/strong> Each layer has its own optimized data structures.<\/li>\n<\/ul>\n\n\n\n
However, this approach also comes at a cost: Mapping logic and data conversions must be maintained for each interface. In smaller projects, the overhead can quickly seem disproportionate\u2014but in more complex applications, the benefits usually outweigh the costs.<\/p>\n\n\n\n
Example 4:<\/strong><\/p>\n\n\n\n
data class UserRegistrationRequest(\n @Size(min = 3) val name: String,\n @Email val email: String\n) {\n fun toDomain() = User.create(name = name, email = email)\n}\n\n@Entity\n@Table(name = \"users\")\ndata class UserEntity(\n @Id val id: String,\n @Column(unique = true) val email: String,\n val name: String,\n @Column(name = \"created_at\") val createdAt: LocalDateTime\n) {\n fun toDomain() = User(id = id, name = name, email = email)\n}<\/code><\/pre>\n\n\n\nTesting<\/h3>\n\n\n\n
Another advantage becomes apparent during testing: Thanks to this clear separation, technical tests can be easily conducted independently of the infrastructure.<\/p>\n\n\n\n
The hexagonal architecture elegantly enables isolated testing. The business logic can be tested entirely without external dependencies, since only the port interfaces need to be replaced with mocks.<\/p>\n\n\n\n
Example 5:<\/strong><\/p>\n\n\n\n
class UserRegistrationServiceTest {\n\n private val mockUserRepository = mockk()\n private val mockUserNotificationService = mockk()\n private val userRegistrationService = UserRegistrationService(\n mockUserRepository, \n mockUserNotificationService\n )\n\n @Test\n fun `should successfully register a user`() {\n \/\/ Arrange\n val user = User (email = \"test@example.com\", name = \"Test User\")\n every { mockUserRepository.existsByEmail(user.email) } returns false\n every { mockUserRepository.save(any()) } returnsArgument 0\n every { mockUserNotificationService.sendWelcomeMessage(any()) } just Runs\n\n \/\/ Act\n userRegistrationService.registerUser(user)\n\n \/\/ Assert\n verify { mockUserRepository.save(any()) }\n verify { mockEmailService.sendWelcomeMessage(user) }\n }\n}<\/code><\/pre>\n\n\n\nBenefits for Sustainable Software Development<\/h3>\n\n\n\n
The hexagonal architecture offers concrete advantages for the long-term maintainability of software:<\/p>\n\n\n\n
- \n
- Flexibility in Technology Decisions:<\/strong> Frameworks or external APIs can be replaced without altering the business logic.<\/li>\n\n\n\n
- Improved testability:<\/strong> Business logic can be tested in a fully isolated environment.<\/li>\n\n\n\n
- Clearer structures:<\/strong> Business and technical aspects are clearly separated; in particular, the business logic is easier to understand and therefore easier to maintain.<\/li>\n\n\n\n
- Parallel development:<\/strong> Teams can work on adapters and business logic in parallel once the interfaces have been defined by ports.<\/li>\n\n\n\n
- Reduced technical debt:<\/strong> Upgrades and refactorings become less risky.<\/li>\n<\/ul>\n\n\n\n
When is it worth using?<\/h3>\n\n\n\n
Despite these advantages, the hexagonal architecture is not the right choice for every project. It is particularly well-suited for:<\/p>\n\n\n\n
- Improved testability:<\/strong> Business logic can be tested in a fully isolated environment.<\/li>\n\n\n\n
- Flexibility in Technology Transitions:<\/strong> Switching from, for example, REST to a message bus requires changes only in the adapter.<\/li>\n\n\n\n
- Infrastructure Assets<\/strong> (or adapter models), on the other hand, are tailored to frameworks or external systems, such as database entities or DTOs for a REST API.<\/li>\n<\/ul>\n\n\n\n
- Layer boundaries are becoming less distinct:<\/strong> When under time pressure, developers tend to blur the boundaries between the layers. As a result, business logic may end up in the presentation layer, or technical details may find their way into the business logic. As a result, the business logic code becomes increasingly difficult to understand; important aspects are harder to identify and can easily be lost during technical adjustments.<\/li>\n\n\n\n