Skip to main content

Hexagonal Infrastructure

Overview​

The Hexagonal Architecture (also known as Ports and Adapters) ensures that the core business logic is independent of external concerns like databases, APIs, and user interfaces. This decoupling improves testability, maintainability, and flexibility in adopting new technologies.

Why Use This Structure?​

  • Separation of Core and External Concerns – The business logic remains unaffected by changes in frameworks, databases, or external services.
  • Flexible Adapters – New technologies can be integrated by adding new adapters without modifying the core logic.
  • Enhanced Testability – Core components can be tested in isolation from infrastructure and external dependencies.

Allowed Directory/Package Names​

Package Hierarchy and Responsibilities​

root/
├── domain/         # Core domain logic (business entities, services, events, value objects)
│   ├── entity/     # Domain entities representing core business objects
│   ├── event/      # Domain events for event-driven design
│   ├── service/    # Business logic within the domain layer
│   ├── valueobject/ # Immutable objects representing concepts with value semantics
│
├── application/    # Application logic coordinating business use cases
│   ├── usecase/    # Application-level business rules
│   ├── port/       # Defines input/output communication for external components
│       ├── input/  # Input ports defining how the application receives data
│       ├── output/ # Output ports defining interactions with external services
│
├── infrastructure/ # External system interactions (adapters, repositories, clients)
│   ├── adapter/    # Bridges between application logic and external dependencies
│       ├── rest/   # REST controllers handling HTTP requests
│       ├── cli/    # Command-line interface components
│       ├── graphql/ # GraphQL API handlers
│       ├── eventhandler/ # Event-driven architecture handlers
│   ├── repository/ # Database interactions, ORM implementations
│   ├── client/     # API clients for external services
│
├── configuration/  # Configuration settings for system setup
│   ├── persistence/ # Persistence layer configuration (database setup)
│   ├── security/    # Security configurations (authentication, authorization)
│   ├── general/     # General application configurations
│
├── messaging/      # Event-driven messaging components (shared between infrastructure & config)

Or for package naming:

com.company.project.domain.*
com.company.project.domain.entity.*
com.company.project.domain.event.*
com.company.project.domain.service.*
com.company.project.domain.valueobject.*

com.company.project.application.*
com.company.project.application.usecase.*
com.company.project.application.port.*
com.company.project.application.port.input.*
com.company.project.application.port.output.*

com.company.project.infrastructure.*
com.company.project.infrastructure.adapter.*
com.company.project.infrastructure.adapter.rest.*
com.company.project.infrastructure.adapter.cli.*
com.company.project.infrastructure.adapter.graphql.*
com.company.project.infrastructure.adapter.eventhandler.*
com.company.project.infrastructure.repository.*
com.company.project.infrastructure.client.*

com.company.project.configuration.*
com.company.project.configuration.persistence.*
com.company.project.configuration.security.*
com.company.project.configuration.general.*

com.company.project.messaging.*

Implementation Notes​

  • Domain Layer (Entities, Services, Value Objects) should be completely independent of external frameworks.

  • Application Layer (Use Cases, Ports) defines how the domain interacts with the outside world without depending on implementations.

  • Infrastructure Layer (Adapters, Repositories, Clients) implements specific technologies and interacts with the external world.

  • Configuration Layer manages system-wide settings, including security, persistence, and general configurations.

  • Messaging Layer is shared between infrastructure and configuration, handling event-driven architectures.

By following Hexagonal Infrastructure, teams can build loosely coupled, testable, and scalable applications while maintaining clear separation of concerns.