System Design (LLD)Hexagonal Architecture

Hexagonal Architecture (Ports & Adapters)

LevelIntermediate

Duration75 mins

TopicHexagonal Architecture

1 / 4

Core Domain at Center

The Architecture That Changed Everything

In 2005, Alistair Cockburn introduced an architectural pattern that would fundamentally change how we think about application structure. He called it Hexagonal Architecture, though it's equally known by its more descriptive name: Ports and Adapters.

The core insight was revolutionary in its simplicity: what if we designed applications so that the business logic at the center knew nothing about the outside world? What if the database, the web framework, the message queue, and the user interface were all interchangeable without touching a single line of business code?

This isn't just an academic exercise. Hexagonal Architecture addresses one of the most persistent problems in software development: the tight coupling between business logic and infrastructure that makes systems rigid, difficult to test, and expensive to change.

What You Will Learn

By the end of this page, you will understand why placing the domain at the center of your architecture creates systems that are easier to test, maintain, and evolve. You'll learn the key principles that make this possible and see how they contrast with traditional layered approaches where infrastructure concerns pervade business logic.

The Problem with Traditional Approaches

To appreciate why Hexagonal Architecture matters, we must first understand what it's solving. Traditional application development typically follows one of two patterns, both of which create problems at scale.

Pattern 1: Database-Centric Development

In database-centric development, the application is designed around the database schema. Business logic is scattered across stored procedures, triggers, and application code that directly references database tables. The application becomes an interface to the database rather than an embodiment of business rules.

Pattern 2: Framework-Centric Development

In framework-centric development, the application is designed to exploit framework features. Controllers contain business logic. Domain objects inherit from framework base classes. Configuration and annotations from the framework pervade business code. The application becomes an extension of the framework rather than a distinct entity.

The Coupling Trap

Both patterns create the same fundamental problem: the business logic—which represents the core value of your application—becomes inseparable from infrastructure choices that should be implementation details. Changing your database or framework becomes a major undertaking that risks breaking business functionality.

Symptoms of Infrastructure Coupling:

How do you know if your application suffers from this coupling? Look for these telltale signs:

Test database required — You cannot run unit tests without a running database because business logic directly queries data
Framework initialization required — You cannot test business rules without bootstrapping the entire framework
Business code contains infrastructure imports — Your domain classes import database libraries, HTTP frameworks, or messaging systems
Changes cascade across layers — A simple business rule change requires modifications in controllers, services, and data access code
Infrastructure decisions are permanent — The mere thought of switching databases or frameworks induces dread

CoupledOrderService.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// ❌ PROBLEMATIC: Business logic tightly coupled to infrastructure
public class OrderService {
    
    // Direct dependency on database connection
    private final JdbcTemplate jdbcTemplate;
    
    // Direct dependency on messaging infrastructure
    private final RabbitTemplate rabbitTemplate;
    
    // Direct dependency on HTTP client for external API
    private final RestTemplate restTemplate;
    
    public OrderService(JdbcTemplate jdbc, RabbitTemplate rabbit, RestTemplate rest) {
        this.jdbcTemplate = jdbc;
        this.rabbitTemplate = rabbit;
        this.restTemplate = rest;
    }
    
    public void submitOrder(OrderRequest request) {
        // Business logic mixed with SQL
        String sql = "INSERT INTO orders (customer_id, total, status) VALUES (?, ?, ?)";
        jdbcTemplate.update(sql, request.getCustomerId(), request.getTotal(), "PENDING");
        
        // Business logic mixed with message queue specifics
        OrderEvent event = new OrderEvent(request.getOrderId(), "SUBMITTED");
        rabbitTemplate.convertAndSend("order.events", event);
        
        // Business logic mixed with HTTP calls
        String inventoryUrl = "http://inventory-service/reserve";
        restTemplate.postForEntity(inventoryUrl, request.getItems(), Void.class);
    }
}
 
/*
 * Problems with this approach:
 * 
 * 1. Cannot test without JDBC, RabbitMQ, and HTTP server running
 * 2. Business rules (what makes an order valid) are buried in SQL
 * 3. Changing to a different database requires rewriting business code
 * 4. Changing messaging system requires rewriting business code
 * 5. The OrderService knows about connection strings, queues, URLs
 * 6. No clear boundary between "what the system does" and "how it does it"
 */

The Hexagonal Solution: Domain at the Center

Hexagonal Architecture proposes a radically different organization. Instead of organizing code by technical layers (controllers, services, repositories), we organize around a central core:

The Domain is the Center

At the absolute center of the application sits the Domain—the business logic, rules, and entities that represent what your application does. This domain is pure: it contains no references to databases, web frameworks, message queues, or any other infrastructure.

The domain speaks only in terms of its own language: Orders, Customers, Products, Pricing Rules, Inventory Policies. It doesn't know if it's running in a web application, a desktop app, or a command-line tool. It doesn't know if data comes from PostgreSQL, MongoDB, or a flat file.

Everything Else is Outside

Everything that isn't pure business logic lives outside the domain. The database is outside. The REST API is outside. The message queue is outside. The email service is outside. Even the user interface is outside.

These external components are not inferior or unimportant—they're essential for a working system. But they are adapters to the domain, not integral parts of it.

Converting Mermaid diagram...

Why a Hexagon?

The hexagonal shape is a visual metaphor, not a strict requirement. Cockburn chose it because:

Multiple sides — Unlike a layered cake with a top and bottom, a hexagon shows that there can be many entry points and exit points to the application
Symmetry — All external actors (whether sending data in or receiving data out) are conceptually equivalent—they're all 'outside'
No privileged direction — Unlike layers where data flows 'down' through the stack, the hexagon emphasizes bidirectional communication through well-defined ports

In practice, you might have 2 ports or 20 ports. The shape doesn't literally matter—what matters is the principle of a protected center.

The Golden Rule

Dependencies point inward. The domain depends on nothing external. External components depend on the domain (through interfaces). This single rule, when followed rigorously, is what makes Hexagonal Architecture work.

Characteristics of the Domain Core

The domain core has specific characteristics that distinguish it from other parts of the system. Understanding these is crucial for proper implementation.

Pure Business Logic

The domain contains business rules expressed in code. These are the policies, constraints, calculations, and workflows that define what your application does—independent of how users access it or where data is stored.

Examples of domain logic:

An order cannot be submitted without at least one line item
Discount percentage cannot exceed 50%
Premium customers get free shipping on orders over $100
Inventory reservation expires after 15 minutes of inactivity

Domain Core Characteristics

•Framework-Agnostic — The domain uses no Spring, Django, Rails, or any other framework imports. It's plain language constructs (classes, interfaces, functions).
•Infrastructure-Ignorant — The domain doesn't know about databases, HTTP, files, or network protocols. It speaks in terms of abstractions defined by the domain itself.
•Side-Effect-Free Core Logic — Business rule calculations are pure functions where possible. Side effects (persistence, notifications) happen at the boundaries, not in the core.
•Rich Domain Model — Entities contain behavior, not just data. An Order knows how to calculate its total, not just store a number.
•Self-Validating — Entities and value objects enforce their own invariants. An invalid Money object should be impossible to construct.
•Testable in Isolation — Domain logic can be tested with simple unit tests—no containers, no databases, no framework bootstrapping.

DomainCore.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// ✅ CLEAN: Domain core with no infrastructure dependencies
package com.example.domain;
 
// Notice: NO framework imports, NO database imports, NO HTTP imports
import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.List;
import java.util.ArrayList;
 
/**
 * Order entity - pure domain logic
 * This class can be tested with zero infrastructure
 */
public class Order {
    private final OrderId id;
    private final CustomerId customerId;
    private final List<LineItem> lineItems;
    private OrderStatus status;
    private final LocalDateTime createdAt;
    
    public Order(OrderId id, CustomerId customerId) {
        this.id = id;
        this.customerId = customerId;
        this.lineItems = new ArrayList<>();
        this.status = OrderStatus.DRAFT;
        this.createdAt = LocalDateTime.now();
    }
    
    // Business rule: Order must have items to be submitted
    public void submit() {
        if (lineItems.isEmpty()) {
            throw new OrderValidationException("Cannot submit an empty order");
        }
        if (status != OrderStatus.DRAFT) {
            throw new InvalidOrderStateException(
                "Can only submit orders in DRAFT status, current: " + status
            );
        }
        this.status = OrderStatus.SUBMITTED;
    }
    
    // Business rule: Calculate total using domain logic
    public Money calculateTotal() {
        return lineItems.stream()
            .map(LineItem::subtotal)
            .reduce(Money.ZERO, Money::add);
    }
    
    // Business rule: Apply discount with domain constraints
    public void applyDiscount(DiscountPolicy policy) {
        BigDecimal discountPercent = policy.calculateDiscount(this);
        if (discountPercent.compareTo(new BigDecimal("50")) > 0) {
            throw new DiscountExceedsLimitException(
                "Discount cannot exceed 50%, got: " + discountPercent + "%"
            );
        }
        // Apply discount to line items...
    }
    
    // Business rule: Premium customers get free shipping
    public ShippingCost calculateShipping(Customer customer, ShippingPolicy policy) {
        if (customer.isPremium() && calculateTotal().isGreaterThan(Money.of(100))) {
            return ShippingCost.FREE;
        }
        return policy.calculate(this);
    }
    
    public void addLineItem(Product product, Quantity quantity) {
        this.lineItems.add(new LineItem(product, quantity));
    }
    
    // Getters - domain objects are typically not anemic
    public OrderId getId() { return id; }
    public OrderStatus getStatus() { return status; }
    public List<LineItem> getLineItems() { return List.copyOf(lineItems); }
}
 
/**
 * Value Object - self-validating, immutable
 */
public record Money(BigDecimal amount, Currency currency) {
    public static final Money ZERO = new Money(BigDecimal.ZERO, Currency.USD);
    
    public Money {
        if (amount == null || amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new InvalidMoneyException("Amount must be non-negative");
        }
        if (currency == null) {
            throw new InvalidMoneyException("Currency is required");
        }
    }
    
    public static Money of(double amount) {
        return new Money(BigDecimal.valueOf(amount), Currency.USD);
    }
    
    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new CurrencyMismatchException(
                "Cannot add " + this.currency + " and " + other.currency
            );
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }
    
    public boolean isGreaterThan(Money other) {
        return this.amount.compareTo(other.amount) > 0;
    }
}

Why Isolation Matters

Isolating the domain from infrastructure isn't about purist architecture—it delivers concrete, measurable benefits that compound over time.

Benefit 1: Instant Testing

When domain logic has no infrastructure dependencies, you can test it in milliseconds with simple unit tests. No database containers to spin up. No mock servers. No HTTP stubs. Just instantiate your domain objects and verify behavior.

This has cascading effects:

Developers run tests constantly (because they're fast)
Bug detection happens during development, not in QA
Refactoring is confident because the test suite provides instant feedback
CI/CD pipelines are fast because the bulk of tests are pure unit tests

OrderTest.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
// ✅ Pure domain tests - run in milliseconds, no infrastructure
class OrderTest {
    
    @Test
    void submitOrder_withItems_changesStatusToSubmitted() {
        // Arrange - just create domain objects
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        order.addLineItem(
            new Product(new ProductId("P1"), "Widget", Money.of(10)),
            new Quantity(2)
        );
        
        // Act
        order.submit();
        
        // Assert
        assertEquals(OrderStatus.SUBMITTED, order.getStatus());
    }
    
    @Test
    void submitOrder_withoutItems_throwsException() {
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        
        assertThrows(OrderValidationException.class, () -> order.submit());
    }
    
    @Test
    void calculateTotal_withMultipleItems_sumsCorrectly() {
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        order.addLineItem(
            new Product(new ProductId("P1"), "Widget", Money.of(10)),
            new Quantity(2)
        );
        order.addLineItem(
            new Product(new ProductId("P2"), "Gadget", Money.of(25)),
            new Quantity(1)
        );
        
        Money total = order.calculateTotal();
        
        assertEquals(Money.of(45), total); // (10*2) + (25*1)
    }
    
    @Test
    void applyDiscount_exceedingLimit_throwsException() {
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        order.addLineItem(
            new Product(new ProductId("P1"), "Expensive Item", Money.of(1000)),
            new Quantity(1)
        );
        
        // Domain policy that would give 60% discount
        DiscountPolicy excessivePolicy = o -> new BigDecimal("60");
        
        assertThrows(DiscountExceedsLimitException.class, 
            () -> order.applyDiscount(excessivePolicy)
        );
    }
    
    @Test
    void premiumCustomer_freeShipping_onLargeOrder() {
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        order.addLineItem(
            new Product(new ProductId("P1"), "Widget", Money.of(150)),
            new Quantity(1)
        );
        Customer premium = new Customer(new CustomerId("C1"), "Alice", true);
        
        ShippingCost shipping = order.calculateShipping(premium, new StandardShippingPolicy());
        
        assertEquals(ShippingCost.FREE, shipping);
    }
}
 
// All these tests:
// - Run in < 10ms each
// - Require no database
// - Require no framework
// - Require no network
// - Test actual business rules

Benefit 2: Technology Flexibility

When the domain doesn't depend on infrastructure, you can change infrastructure without touching business logic.

Real-world scenarios where this matters:

Migrating from MySQL to PostgreSQL
Switching from RabbitMQ to Kafka
Moving from REST to GraphQL
Replacing an external payment provider
Scaling from a monolith to microservices

In a properly isolated architecture, each of these changes affects only the adapters—the bridge code between your domain and external systems. The domain itself remains unchanged.

Coupled Architecture

•Change database → Rewrite business logic
•Change framework → Rewrite services
•Add new UI → Duplicate validation
•Test business rules → Set up infrastructure
•Infrastructure bugs → Domain failures

Hexagonal Architecture

•Change database → Write new adapter
•Change framework → Write new adapter
•Add new UI → New adapter, same domain
•Test business rules → Pure unit tests
•Infrastructure bugs → Domain unaffected

Benefit 3: Focused Development

When developers work on business logic, they work purely on business problems. They're not distracted by database connection issues, HTTP serialization, or framework quirks. The cognitive load is dramatically lower.

Conversely, when developers work on infrastructure (implementing adapters), they have a clear contract to fulfill without needing to understand all the business intricacies.

This separation allows for genuine division of labor. Domain experts can focus on domain code. Infrastructure specialists can focus on adapters. The interface between them is a well-defined contract.

The Cost is Upfront, The Benefit is Ongoing

Hexagonal Architecture requires more upfront design. You must define interfaces (ports) before implementation. You must resist the temptation to 'just use the framework.' But this investment pays dividends throughout the system's lifetime. Systems with clear domain boundaries are dramatically cheaper to maintain and evolve.

The Inside-Out Design Approach

Hexagonal Architecture fundamentally changes how you design applications. Instead of starting from the outside (UI, API, database schema), you start from the inside.

Traditional Outside-In Design:

Design the database schema
Generate or write data access objects
Create services that manipulate the data
Build controllers that expose the services
Sprinkle business rules throughout

Hexagonal Inside-Out Design:

Understand the business domain through domain experts
Model entities, value objects, and domain services
Define use cases as input ports
Define required external capabilities as output ports
Implement adapters to connect ports to real infrastructure

Design Approach Comparison
Aspect	Outside-In	Inside-Out (Hexagonal)
Starting question	What data do we store?	What does the business do?
Primary artifact	Database schema	Domain model
Business rules location	Scattered across layers	Concentrated in domain
Technology decisions	Made first, hard to change	Made last, easy to change
Test strategy	Integration tests primary	Unit tests primary
Development sequence	Data → Services → UI	Domain → Ports → Adapters

Practical Inside-Out Process:

Step 1: Domain Modeling Session

Gather domain experts and developers. Use techniques like Event Storming or Domain Storytelling to understand the business processes. Identify key entities (things with identity), value objects (things defined by attributes), and domain events (important things that happen).

Step 2: Code the Domain

Translate the model into code. Create entity classes, value objects, and domain services. Define invariants (rules that must always be true). At this stage, you have no database, no web framework—just pure domain code.

Step 3: Define Input Ports

For each use case the application must support, create an interface. These interfaces express what the application can do without specifying how requests arrive.

Step 4: Define Output Ports

For each external capability the domain needs (storing data, sending notifications, checking external systems), create an interface. These express what the domain needs without specifying how to get it.

Step 5: Implement Adapters

Now—and only now—choose your infrastructure. Implement adapters that connect your ports to real systems. The domain doesn't change based on these choices.

Delay Infrastructure Decisions

One of the most valuable aspects of Hexagonal Architecture is that it allows you to delay infrastructure decisions. You can develop, test, and validate your domain logic before committing to PostgreSQL vs MongoDB, REST vs GraphQL, or Kafka vs RabbitMQ. When you finally make these decisions, they're informed by real understanding of what your domain actually needs.

Common Misconceptions

Hexagonal Architecture is frequently misunderstood. Let's address the most common misconceptions that lead to failed implementations.

Misconceptions to Avoid

•Misconception: It's about the hexagon shape — The hexagon is just a visual metaphor. You might have 3 ports or 30. The number of sides doesn't matter. What matters is the clean separation between inside (domain) and outside (infrastructure).
•Misconception: It's just layered architecture with different names — Hexagonal Architecture inverts dependencies. In traditional layers, business logic depends on data access. In hexagonal, data access adapters depend on domain-defined interfaces. This inversion is fundamental, not cosmetic.
•Misconception: Every project needs it — Hexagonal Architecture adds complexity. For simple CRUD applications, scripts, or prototypes, it may be overkill. It shines when domain complexity is high, when infrastructure might change, or when testability is paramount.
•Misconception: It means no frameworks — You absolutely use frameworks—but in adapters, not in the domain. Spring/Django/etc. are fantastic for HTTP handling, DI, and infrastructure concerns. They just shouldn't leak into your business logic.
•Misconception: Ports are just interfaces — Ports represent application boundaries, not just abstractions. An input port is a use case contract. An output port is a required capability. They're conceptually different from generic interfaces.
•Misconception: It solves all architecture problems — Hexagonal Architecture addresses coupling between domain and infrastructure. It doesn't address scalability, team organization, deployment strategies, or many other architectural concerns.

The Most Dangerous Misconception

The most dangerous misconception is thinking you're doing Hexagonal Architecture just because you have 'clean code' or 'service layers.' If your domain classes import database annotations or your entities extend framework classes, you don't have dependency inversion—you have coupled code organized into folders. The structure looks right but the dependencies point the wrong way.

Summary: Core Domain at Center

We've established the foundational principle of Hexagonal Architecture: the domain sits at the center, insulated from all external concerns. Let's consolidate what this means:

Key Takeaways

•The domain is the core value — Business logic is what makes your application unique. It should be protected from infrastructure churn.
•Everything external is an adapter — Databases, frameworks, UIs, and external services are all adapters to your domain, not parts of it.
•Dependencies point inward — The domain defines interfaces. External components implement them. Never the reverse.
•Isolation enables testing — Pure domain logic can be tested in milliseconds without infrastructure.
•Isolation enables change — When infrastructure is behind interfaces, it can be replaced without touching business logic.
•Design inside-out — Start with the domain, define ports, then implement adapters. Technology choices come last, not first.

What's Next:

Now that we understand the central principle—domain at the center—we need to understand how the domain communicates with the outside world. In the next page, we'll explore Ports, the interfaces that define what the application can do (input ports) and what it needs (output ports). Ports are the formalized contracts that make the hexagonal approach work.

Page Complete

You now understand the core principle of Hexagonal Architecture: placing your domain at the center, isolated from infrastructure concerns. This enables testing, flexibility, and focused development. Next, we'll dive deep into Ports—the interfaces that define the boundaries between your domain and the outside world.

1 / 4

Loading learning content...

System Design (LLD)Hexagonal Architecture

Hexagonal Architecture (Ports & Adapters)

LevelIntermediate

Duration75 mins

TopicHexagonal Architecture

1 / 4

Core Domain at Center

The Architecture That Changed Everything

What You Will Learn

The Problem with Traditional Approaches

Pattern 1: Database-Centric Development

Pattern 2: Framework-Centric Development

The Coupling Trap

Symptoms of Infrastructure Coupling:

How do you know if your application suffers from this coupling? Look for these telltale signs:

Test database required — You cannot run unit tests without a running database because business logic directly queries data
Framework initialization required — You cannot test business rules without bootstrapping the entire framework
Business code contains infrastructure imports — Your domain classes import database libraries, HTTP frameworks, or messaging systems
Changes cascade across layers — A simple business rule change requires modifications in controllers, services, and data access code
Infrastructure decisions are permanent — The mere thought of switching databases or frameworks induces dread

CoupledOrderService.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// ❌ PROBLEMATIC: Business logic tightly coupled to infrastructure
public class OrderService {
    
    // Direct dependency on database connection
    private final JdbcTemplate jdbcTemplate;
    
    // Direct dependency on messaging infrastructure
    private final RabbitTemplate rabbitTemplate;
    
    // Direct dependency on HTTP client for external API
    private final RestTemplate restTemplate;
    
    public OrderService(JdbcTemplate jdbc, RabbitTemplate rabbit, RestTemplate rest) {
        this.jdbcTemplate = jdbc;
        this.rabbitTemplate = rabbit;
        this.restTemplate = rest;
    }
    
    public void submitOrder(OrderRequest request) {
        // Business logic mixed with SQL
        String sql = "INSERT INTO orders (customer_id, total, status) VALUES (?, ?, ?)";
        jdbcTemplate.update(sql, request.getCustomerId(), request.getTotal(), "PENDING");
        
        // Business logic mixed with message queue specifics
        OrderEvent event = new OrderEvent(request.getOrderId(), "SUBMITTED");
        rabbitTemplate.convertAndSend("order.events", event);
        
        // Business logic mixed with HTTP calls
        String inventoryUrl = "http://inventory-service/reserve";
        restTemplate.postForEntity(inventoryUrl, request.getItems(), Void.class);
    }
}
 
/*
 * Problems with this approach:
 * 
 * 1. Cannot test without JDBC, RabbitMQ, and HTTP server running
 * 2. Business rules (what makes an order valid) are buried in SQL
 * 3. Changing to a different database requires rewriting business code
 * 4. Changing messaging system requires rewriting business code
 * 5. The OrderService knows about connection strings, queues, URLs
 * 6. No clear boundary between "what the system does" and "how it does it"
 */

The Hexagonal Solution: Domain at the Center

Hexagonal Architecture proposes a radically different organization. Instead of organizing code by technical layers (controllers, services, repositories), we organize around a central core:

The Domain is the Center

Everything Else is Outside

These external components are not inferior or unimportant—they're essential for a working system. But they are adapters to the domain, not integral parts of it.

Converting Mermaid diagram...

Why a Hexagon?

The hexagonal shape is a visual metaphor, not a strict requirement. Cockburn chose it because:

Multiple sides — Unlike a layered cake with a top and bottom, a hexagon shows that there can be many entry points and exit points to the application
Symmetry — All external actors (whether sending data in or receiving data out) are conceptually equivalent—they're all 'outside'
No privileged direction — Unlike layers where data flows 'down' through the stack, the hexagon emphasizes bidirectional communication through well-defined ports

In practice, you might have 2 ports or 20 ports. The shape doesn't literally matter—what matters is the principle of a protected center.

The Golden Rule

Characteristics of the Domain Core

The domain core has specific characteristics that distinguish it from other parts of the system. Understanding these is crucial for proper implementation.

Pure Business Logic

Examples of domain logic:

An order cannot be submitted without at least one line item
Discount percentage cannot exceed 50%
Premium customers get free shipping on orders over $100
Inventory reservation expires after 15 minutes of inactivity

Domain Core Characteristics

•Framework-Agnostic — The domain uses no Spring, Django, Rails, or any other framework imports. It's plain language constructs (classes, interfaces, functions).
•Infrastructure-Ignorant — The domain doesn't know about databases, HTTP, files, or network protocols. It speaks in terms of abstractions defined by the domain itself.
•Side-Effect-Free Core Logic — Business rule calculations are pure functions where possible. Side effects (persistence, notifications) happen at the boundaries, not in the core.
•Rich Domain Model — Entities contain behavior, not just data. An Order knows how to calculate its total, not just store a number.
•Self-Validating — Entities and value objects enforce their own invariants. An invalid Money object should be impossible to construct.
•Testable in Isolation — Domain logic can be tested with simple unit tests—no containers, no databases, no framework bootstrapping.

DomainCore.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// ✅ CLEAN: Domain core with no infrastructure dependencies
package com.example.domain;
 
// Notice: NO framework imports, NO database imports, NO HTTP imports
import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.List;
import java.util.ArrayList;
 
/**
 * Order entity - pure domain logic
 * This class can be tested with zero infrastructure
 */
public class Order {
    private final OrderId id;
    private final CustomerId customerId;
    private final List<LineItem> lineItems;
    private OrderStatus status;
    private final LocalDateTime createdAt;
    
    public Order(OrderId id, CustomerId customerId) {
        this.id = id;
        this.customerId = customerId;
        this.lineItems = new ArrayList<>();
        this.status = OrderStatus.DRAFT;
        this.createdAt = LocalDateTime.now();
    }
    
    // Business rule: Order must have items to be submitted
    public void submit() {
        if (lineItems.isEmpty()) {
            throw new OrderValidationException("Cannot submit an empty order");
        }
        if (status != OrderStatus.DRAFT) {
            throw new InvalidOrderStateException(
                "Can only submit orders in DRAFT status, current: " + status
            );
        }
        this.status = OrderStatus.SUBMITTED;
    }
    
    // Business rule: Calculate total using domain logic
    public Money calculateTotal() {
        return lineItems.stream()
            .map(LineItem::subtotal)
            .reduce(Money.ZERO, Money::add);
    }
    
    // Business rule: Apply discount with domain constraints
    public void applyDiscount(DiscountPolicy policy) {
        BigDecimal discountPercent = policy.calculateDiscount(this);
        if (discountPercent.compareTo(new BigDecimal("50")) > 0) {
            throw new DiscountExceedsLimitException(
                "Discount cannot exceed 50%, got: " + discountPercent + "%"
            );
        }
        // Apply discount to line items...
    }
    
    // Business rule: Premium customers get free shipping
    public ShippingCost calculateShipping(Customer customer, ShippingPolicy policy) {
        if (customer.isPremium() && calculateTotal().isGreaterThan(Money.of(100))) {
            return ShippingCost.FREE;
        }
        return policy.calculate(this);
    }
    
    public void addLineItem(Product product, Quantity quantity) {
        this.lineItems.add(new LineItem(product, quantity));
    }
    
    // Getters - domain objects are typically not anemic
    public OrderId getId() { return id; }
    public OrderStatus getStatus() { return status; }
    public List<LineItem> getLineItems() { return List.copyOf(lineItems); }
}
 
/**
 * Value Object - self-validating, immutable
 */
public record Money(BigDecimal amount, Currency currency) {
    public static final Money ZERO = new Money(BigDecimal.ZERO, Currency.USD);
    
    public Money {
        if (amount == null || amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new InvalidMoneyException("Amount must be non-negative");
        }
        if (currency == null) {
            throw new InvalidMoneyException("Currency is required");
        }
    }
    
    public static Money of(double amount) {
        return new Money(BigDecimal.valueOf(amount), Currency.USD);
    }
    
    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new CurrencyMismatchException(
                "Cannot add " + this.currency + " and " + other.currency
            );
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }
    
    public boolean isGreaterThan(Money other) {
        return this.amount.compareTo(other.amount) > 0;
    }
}

Why Isolation Matters

Isolating the domain from infrastructure isn't about purist architecture—it delivers concrete, measurable benefits that compound over time.

Benefit 1: Instant Testing

This has cascading effects:

Developers run tests constantly (because they're fast)
Bug detection happens during development, not in QA
Refactoring is confident because the test suite provides instant feedback
CI/CD pipelines are fast because the bulk of tests are pure unit tests

OrderTest.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
// ✅ Pure domain tests - run in milliseconds, no infrastructure
class OrderTest {
    
    @Test
    void submitOrder_withItems_changesStatusToSubmitted() {
        // Arrange - just create domain objects
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        order.addLineItem(
            new Product(new ProductId("P1"), "Widget", Money.of(10)),
            new Quantity(2)
        );
        
        // Act
        order.submit();
        
        // Assert
        assertEquals(OrderStatus.SUBMITTED, order.getStatus());
    }
    
    @Test
    void submitOrder_withoutItems_throwsException() {
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        
        assertThrows(OrderValidationException.class, () -> order.submit());
    }
    
    @Test
    void calculateTotal_withMultipleItems_sumsCorrectly() {
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        order.addLineItem(
            new Product(new ProductId("P1"), "Widget", Money.of(10)),
            new Quantity(2)
        );
        order.addLineItem(
            new Product(new ProductId("P2"), "Gadget", Money.of(25)),
            new Quantity(1)
        );
        
        Money total = order.calculateTotal();
        
        assertEquals(Money.of(45), total); // (10*2) + (25*1)
    }
    
    @Test
    void applyDiscount_exceedingLimit_throwsException() {
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        order.addLineItem(
            new Product(new ProductId("P1"), "Expensive Item", Money.of(1000)),
            new Quantity(1)
        );
        
        // Domain policy that would give 60% discount
        DiscountPolicy excessivePolicy = o -> new BigDecimal("60");
        
        assertThrows(DiscountExceedsLimitException.class, 
            () -> order.applyDiscount(excessivePolicy)
        );
    }
    
    @Test
    void premiumCustomer_freeShipping_onLargeOrder() {
        Order order = new Order(new OrderId("123"), new CustomerId("C1"));
        order.addLineItem(
            new Product(new ProductId("P1"), "Widget", Money.of(150)),
            new Quantity(1)
        );
        Customer premium = new Customer(new CustomerId("C1"), "Alice", true);
        
        ShippingCost shipping = order.calculateShipping(premium, new StandardShippingPolicy());
        
        assertEquals(ShippingCost.FREE, shipping);
    }
}
 
// All these tests:
// - Run in < 10ms each
// - Require no database
// - Require no framework
// - Require no network
// - Test actual business rules

Benefit 2: Technology Flexibility

When the domain doesn't depend on infrastructure, you can change infrastructure without touching business logic.

Real-world scenarios where this matters:

Migrating from MySQL to PostgreSQL
Switching from RabbitMQ to Kafka
Moving from REST to GraphQL
Replacing an external payment provider
Scaling from a monolith to microservices

In a properly isolated architecture, each of these changes affects only the adapters—the bridge code between your domain and external systems. The domain itself remains unchanged.

Coupled Architecture

•Change database → Rewrite business logic
•Change framework → Rewrite services
•Add new UI → Duplicate validation
•Test business rules → Set up infrastructure
•Infrastructure bugs → Domain failures

Hexagonal Architecture

•Change database → Write new adapter
•Change framework → Write new adapter
•Add new UI → New adapter, same domain
•Test business rules → Pure unit tests
•Infrastructure bugs → Domain unaffected

Benefit 3: Focused Development

Conversely, when developers work on infrastructure (implementing adapters), they have a clear contract to fulfill without needing to understand all the business intricacies.

This separation allows for genuine division of labor. Domain experts can focus on domain code. Infrastructure specialists can focus on adapters. The interface between them is a well-defined contract.

The Cost is Upfront, The Benefit is Ongoing

The Inside-Out Design Approach

Hexagonal Architecture fundamentally changes how you design applications. Instead of starting from the outside (UI, API, database schema), you start from the inside.

Traditional Outside-In Design:

Design the database schema
Generate or write data access objects
Create services that manipulate the data
Build controllers that expose the services
Sprinkle business rules throughout

Hexagonal Inside-Out Design:

Understand the business domain through domain experts
Model entities, value objects, and domain services
Define use cases as input ports
Define required external capabilities as output ports
Implement adapters to connect ports to real infrastructure

Design Approach Comparison
Aspect	Outside-In	Inside-Out (Hexagonal)
Starting question	What data do we store?	What does the business do?
Primary artifact	Database schema	Domain model
Business rules location	Scattered across layers	Concentrated in domain
Technology decisions	Made first, hard to change	Made last, easy to change
Test strategy	Integration tests primary	Unit tests primary
Development sequence	Data → Services → UI	Domain → Ports → Adapters

Practical Inside-Out Process:

Step 1: Domain Modeling Session

Step 2: Code the Domain

Step 3: Define Input Ports

For each use case the application must support, create an interface. These interfaces express what the application can do without specifying how requests arrive.

Step 4: Define Output Ports

Step 5: Implement Adapters

Now—and only now—choose your infrastructure. Implement adapters that connect your ports to real systems. The domain doesn't change based on these choices.

Delay Infrastructure Decisions

Common Misconceptions

Hexagonal Architecture is frequently misunderstood. Let's address the most common misconceptions that lead to failed implementations.

Misconceptions to Avoid

•Misconception: It's about the hexagon shape — The hexagon is just a visual metaphor. You might have 3 ports or 30. The number of sides doesn't matter. What matters is the clean separation between inside (domain) and outside (infrastructure).
•Misconception: It's just layered architecture with different names — Hexagonal Architecture inverts dependencies. In traditional layers, business logic depends on data access. In hexagonal, data access adapters depend on domain-defined interfaces. This inversion is fundamental, not cosmetic.
•Misconception: Every project needs it — Hexagonal Architecture adds complexity. For simple CRUD applications, scripts, or prototypes, it may be overkill. It shines when domain complexity is high, when infrastructure might change, or when testability is paramount.
•Misconception: It means no frameworks — You absolutely use frameworks—but in adapters, not in the domain. Spring/Django/etc. are fantastic for HTTP handling, DI, and infrastructure concerns. They just shouldn't leak into your business logic.
•Misconception: Ports are just interfaces — Ports represent application boundaries, not just abstractions. An input port is a use case contract. An output port is a required capability. They're conceptually different from generic interfaces.
•Misconception: It solves all architecture problems — Hexagonal Architecture addresses coupling between domain and infrastructure. It doesn't address scalability, team organization, deployment strategies, or many other architectural concerns.

The Most Dangerous Misconception

Summary: Core Domain at Center

We've established the foundational principle of Hexagonal Architecture: the domain sits at the center, insulated from all external concerns. Let's consolidate what this means:

Key Takeaways

•The domain is the core value — Business logic is what makes your application unique. It should be protected from infrastructure churn.
•Everything external is an adapter — Databases, frameworks, UIs, and external services are all adapters to your domain, not parts of it.
•Dependencies point inward — The domain defines interfaces. External components implement them. Never the reverse.
•Isolation enables testing — Pure domain logic can be tested in milliseconds without infrastructure.
•Isolation enables change — When infrastructure is behind interfaces, it can be replaced without touching business logic.
•Design inside-out — Start with the domain, define ports, then implement adapters. Technology choices come last, not first.

What's Next:

Page Complete

1 / 4