The Only Multi-Module Hexagonal Architecture: A Message Hub Case Study

KakaoBank's Message Hub System serves as middleware that extracts customer information from various services and delivers messages to UMS. This system organizes 4 microservices—api, data-api, loader, consumer—into a single domain according to purpose.

The existing individual hexagonal architecture configuration caused business logic and secondary adapters to be duplicated across services. In addition, the system faced the technical challenge of being unable to freely scale out in a limited database connection pool environment.

To solve this, the team refactored into a multi-module hexagonal structure within a single project and source. They separated the package-based configuration into module units, structured as follows.

• Primary Adapter Modules: Configure each service and handle external requests.
• Core Module: Contains the port interfaces and the actual business logic.
• Secondary Adapter Modules: Handle implementations for interactions with databases or external infrastructure.

Through this structure, one hexagonal architecture is completed with a combination of 1 primary adapter + 1 core module + 1 or more secondary adapters. This prevents code duplication while adhering to clean architecture principles and enabling flexible dependency management.