Hexagonal Architecture 101
This content is summary form me only , if content is not correct i am apologize.
Ok , We are going to study Hexagonal Architecture ….
Hexagonal architecture concept
Hexagonal architecture is introduced by Alistair Cockburn and written on his blog in 2005. It is built based on two main patterns:
Hexagonal represents business logic. It does not care about your framework development, your technology stack and your language code. It helps you define decoupled code structure, isolated with external components and easy-to-run tests.
Before diving into the details of Hexagonal Architecture, let’s first examine the current system flow.
The current system flow does not follow Hexagonal Architecture.
We will convert to hexagonal architecture.
Next, we will transform it into a standard Hexagonal Architecture design.
Let go , We will learn about the main components of hexagonal architecture
Core
What is Core in Hexagonal Architecture?
Core is the center of all business logic in Hexagonal Architecture, consisting of:
- Domain → Data structures and business rules (Entities, Value Objects, Aggregates).
- Services → Manage processes (Use Cases) and execute business logic.
- Ports (Interfaces) → Define how Core communicates with Adapters for external interactions.
How Does Core Work?
- Independent of Infrastructure (e.g., Database, API, UI).
- Uses Ports as connection points for Adapters.
- Executes Business Logic without direct interaction with external systems.
Key Principles of Core
- Core contains all Business Logic
- Separated from Infrastructure using Ports
- Only manages data and system rules
Services
What is a Service in Hexagonal Architecture?
In Hexagonal Architecture, a Service is responsible for executing business logic within the Core. It acts as the Application Logic Layer, ensuring that the business rules defined in the Domain are executed correctly.
A Service should only interact with Domain Models and communicate with Adapters via Ports. It must remain independent of infrastructure components such as databases, external APIs, or user interfaces.
Key Characteristics of a Service
- Handles Business Logic
- Ensures that the rules defined in the Domain are applied correctly.
- Processes operations such as PlaceOrder, CancelOrder, ProcessPayment.
2. Does Not Directly Depend on Adapters
- Uses Ports (Interfaces) to communicate with external systems.
- Example: Instead of calling a payment API directly, it calls a PaymentGateway interface.
3. Encapsulates Use Cases
- Defines how business operations should be executed step-by-step.
- Example: OrderService manages the order process, ensuring inventory is checked before confirming an order.
4. Coordinates Between Domain and Adapters
- Fetches or manipulates data using Domain Entities.
- Calls Adapters via Ports when external interactions are needed.
Key Principles of Services
- A Service executes business logic within the Core.
- It should not directly interact with external systems but instead use Ports and Adapters.
- Services encapsulate application use cases such as processing an order or handling user authentication.
- They coordinate interactions between the Domain and external systems through defined interfaces.
Domain
What is Domain in Hexagonal Architecture?
In Hexagonal Architecture, the Domain represents the models and business rules that define the boundaries of the system. It is part of the Core and serves as the central structure for data and business logic.
Get HashtagF’s stories in your inbox
Join Medium for free to get updates from this writer.
Key Components of the Domain
- Entities (Business Objects)
- Represent the main data structures of the system, such as User, Order, Product.
- Contain their own business logic, like price calculations or validation rules.
2. Value Objects
- Represent data without an identity, used alongside Entities (e.g., Money, Address).
- They are immutable (cannot be changed once created).
3. Aggregates (A Group of Related Entities)
- For example, Order may contain OrderItem as part of the same Aggregate.
- Ensures consistency within its own scope.
Key Principles of Domain
- Independent from Infrastructure → It does not depend on databases, APIs, or external systems.
- Works through Ports → Allows interaction with Services and Adapters without direct dependencies.
- Defines System Boundaries → Services can only operate within the constraints of the Domain.
4. Domain Services
- Handles business logic that involves multiple entities, such as PricingService.
- Encapsulates complex rules that do not naturally fit within a single entity.
Ports
What is a Port in Hexagonal Architecture?
A Port is an interface that defines how the Core communicates with Adapters without depending on infrastructure details such as databases, APIs, or UI.
Two Main Types of Ports
- Inbound Port (Primary Port)
- Defines the input that Core accepts, such as requests from APIs or UI.
- Typically used with Application Services.
- Example: OrderService receiving requests from a controller.
2. Outbound Port (Secondary Port)
- Defines the output that Core needs, such as database queries or external API calls.
- Usually defined as an interface that Adapters must implement.
- Example: PaymentGateway that Core uses for payment processing.
Key Principles of Ports
- A Port is an Interface connecting Core with Adapters.
- Inbound Ports receive input into Core.
- Outbound Ports allow Core to communicate with external systems.
- Core uses Ports without depending on Adapter implementations.
Adapters
Adapter in Hexagonal Architecture: Driver and Driven
In Hexagonal Architecture, Adapters are categorized into two types based on the Driver / Driven concept, which explains how the Core remains the center of the system, interacting with external components through Ports.
- Driver Adapter (Primary Adapter) → Drives the Core
A Driver Adapter is an Inbound Adapter that sends commands into the Core through Inbound Ports.
Characteristics of Driver Adapter
- Active component → Initiates interactions with Core.
- Works from the outside into Core.
- Examples:
- REST API Controllers → Receives HTTP requests and calls Core services.
- GraphQL Resolvers → Fetches data based on queries.
- CLI Commands → Takes user input and triggers Core processes.
2. Driven Adapter (Secondary Adapter) → Supports the Core
A Driven Adapter is an Outbound Adapter that receives commands from Core through Outbound Ports and interacts with external systems.
Characteristics of Driven Adapter
- Passive component → Executes requests from Core.
- Works from Core to external systems.
- Examples:
- Database Repositories → Handles data persistence.
- External API Clients → Calls third-party services like Stripe or PayPal.
- Message Queue Adapters → Sends messages to Kafka or RabbitMQ.
Key Principles of Adapter
- Driver Adapter (Inbound) drives the Core by sending commands.
- Driven Adapter (Outbound) supports the Core by processing external interactions.
- This separation keeps the Core independent and flexible.
![Hexagonal Architecture 101 [Thai Version]](https://miro.medium.com/v2/resize:fit:1358/format:webp/1*ZgiSHaVTxb93C22C34Y_Yg.png)
