liveBook · Manning

Chapter 5: Hexagonal Architecture: Protecting the Core: The Power of Ports and Adapters

What you will learn in chapter 5 of Grokking Software Architecture

This chapter introduction previews decoupling business logic from external systems and the vocabulary, diagram, code, and origins of hexagonal architecture.

After this chapter you will be able to

What it builds on

Section by section

Introduction

This chapter introduction previews decoupling business logic from external systems and the vocabulary, diagram, code, and origins of hexagonal architecture.

Introduction

The introduction identifies how a database can anchor a layered application and presents a protected core as the alternative organizing idea.

Key terms: Layers, Downward Dependency Rule, infrastructure, business logic, protected Core, Hexagonal Architecture, Ports and Adapters, Testability, Maintainability

5.2 Decoupling the Core: Breaking Free from "Database Gravity"

This section introduces how downward dependencies in a traditional layered architecture can pull design toward the database.

Key terms: Four-Layer Architecture, Downward Dependency Rule, Database-Driven Design

5.2.1 The “Database First” Trap

This section shows how database-shaped domain code and misplaced database-layer logic undermine separation of concerns, testability, and resilience to database changes.

Key terms: Domain First, Database First, Database Gravity, Foreign Key, SQL Row Version, data access layer, business rules, Validation in the Repository, Formatting in the Database, Separation of Concerns

5.2.2 The Clarity Engineer's Shift in Focus: Inside vs. Outside

This section shifts architectural thinking from top-and-bottom layers to inside-and-outside regions, defining decoupling the core as keeping business logic independent of outside technology.

Key terms: Layers, Regions, Inside, Outside, Boundary, Boundary Keeper, Decoupling the Core, high-value business logic

5.2.3 Analogy: The "Clean Room" Lab

The clean-room analogy shows how hexagonal architecture protects business logic by making the outside world communicate through core-defined interfaces.

Key terms: Domain Core, Business Logic, Clean Room, Outside, Airlock, Interface, Boundary Keeper, Guardian of the Airlock, Port, structural walls

5.3 Inside, Ports, and Adapters

The section states the aim of protecting the core while allowing data to pass in and out without bringing coupling with it.

Key terms: Core, data, coupling

5.3.1 1. The Inside (The Core)

Defines the hexagonal architecture core as business logic with separate rule and workflow responsibilities, kept independent of outside technology.

Key terms: Inside, Domain, Entities, Orchestrator, Application Layer, Service Layer, Golden Rule, Outside

5.3.2 2. The Ports (The Interfaces)

This section defines ports as the core’s interface contracts and distinguishes the contracts for using the application from those for services it needs.

Key terms: Core, Ports, Interface, contract, Primary Ports (Driving), Secondary Ports (Driven), IOrderService, IOrderRepository

5.3.3 3. The Adapters (The Translators)

Explains how driving and driven adapters translate between the outside world and the Core, while inward-pointing dependencies protect the Core from infrastructure details.

Key terms: Primary Adapters (Driving), Secondary Adapters (Driven), Primary Port, Secondary Port, Anti-Corruption Layer, Core's language, business logic, Inversion, Dependency, Data

5.3.4 Analogy: The Universal Serial Bus (USB)

Uses a USB laptop analogy to explain how a core communicates through ports with interchangeable adapters without changing its code.

Key terms: Inside, Core, Port, Interface, Adapter, decoupled, SQL database, file system adapter

5.3.5 A More Fun Analogy: The Castle and The Drawbridge

The castle analogy shows how ports and adapters protect the core, then identifies common ways that boundary can break down.

Key terms: Core, Ports, Primary Adapters, Secondary Adapters, Domain Object, Adapters, SQL, Mongo, Leaky Port, CRUD Obsession

5.4 Diagram: The Map of the Hexagon

Introduces the hexagonal architecture diagram as an outside-in map that makes the boundary between inside and outside visible.

Key terms: Hexagonal Architecture diagram, Boundary, Layered Architecture diagram, outside-in

5.4.1 Reading the Map

Explains how to read a hexagonal architecture diagram: a self-contained domain at the center, distinct driving and driven sides, and a shape that represents multiple ways to connect.

Key terms: domain, Clean Room, business entities and logic, Core, driving side, driven side, initiators, Primary Adapter, Primary Port, Secondary Port

5.5 Code Snippet: The "Universal Power Outlet"

Introduces a server-monitoring example to show why swapping ports-and-adapters implementations is preferable to scattering environment checks through alerting code.

Key terms: Ports and Adapters, Server Monitoring System, SMS, Console, swapping plugs

5.5.1 The “Before” Code: The Infrastructure Anchor

This section uses a hardwired SMS example to show how infrastructure coupling makes business logic hard to test and vendors hard to change, then contrasts layered and hexagonal dependency direction.

Key terms: ServerMonitor, Twilio, Testing Nightmare, Vendor Lock-in, layered architecture, DIP, dependency arrow, infrastructure, hexagonal

5.5.2 The Hexagonal Solution: One Core, Many Plugs

Shows how an alerting core uses a domain-defined port, interchangeable infrastructure adapters, constructor injection, and a composition root to keep infrastructure choices out of business logic.

Key terms: Secondary Port, Driven Port, Secondary Adapters, Inside, Outside, Domain Layer, ServerMonitor, socket, constructor, Dependency Injection

5.5.3 Making the Hexagon Visible: The Project Structure

This section shows how a Server Monitor project structure makes the hexagonal boundary visible and keeps dependencies pointing toward the core.

Key terms: Core, Domain, Ports, Infrastructure, Adapters, Dependencies Point In

5.5.4 The Strategic Payoff: The "Click" of the Plug

This section explains how protecting the core with ports and adapters enables reuse, isolated changes, and reliable tests, while weighing the added complexity and connecting hexagonal architecture to related approaches.

Key terms: Architectural Sovereignty, Core, Inside, Outside, Primary Adapter, Universal Application Logic, Testability, Port, Airplane Mode, Maintainability

5.6 The Dork Side: Cockburn's Hexagons and the Shape of Logic

The section explains the entanglement Cockburn sought to solve with Hexagonal Architecture: business logic tied to external technology is hard to test, run, and change.

Key terms: entanglement, core business logic, external technologies, hard-wired, Hexagonal Architecture, business logic

5.6.1 The Origin Story: Alistair and the Weather App

This origin story explains how UI and database dependencies frustrated automatic testing of application logic, and why Cockburn questioned conventional layered-architecture drawings.

Key terms: application logic, GUI, database, Layered Architecture, UI

5.6.2 The Geometry of "Enough Room"

The section explains why the hexagon is a diagramming choice, not a requirement for six ports, and why “Ports and Adapters” better names the pattern.

Key terms: Application Core, ports, Hexagonal Architecture, Ports and Adapters, adapters

5.7 The Rescue Mission: Can I Migrate a Legacy App to Hexagonal?

This section explains how to migrate a legacy application incrementally by building new hexagonal logic around parts of the old system.

Key terms: Strangler Fig Pattern, Hexagonal boundary, Port, Adapter, legacy database

5.7.1 How to execute the "Strangler" Refactor:

This section outlines a gradual way to move legacy application logic into a hexagonal structure and cautions against doing so without considering the cost.

Key terms: Seam, Hexagonal Outpost, Legacy Adapter, Port, Hexagon, Complexity Tax

5.8 The Cost of Decoupling: Why You Might Not Want (or Need!) Hexagonal Architecture

Introduces the decision of whether hexagonal architecture’s isolation and testability are worth its costs compared with layered architecture.

Key terms: Layered Architecture, Hexagonal Architecture, isolation, testability, trade-offs

5.8.1 The Complexity Tax (Overhead)

This section explains the extra code hexagonal architecture requires, when that overhead may not be worthwhile, and the distinction between a DTO and a Command Object.

Key terms: Complexity Tax, Hexagonal Architecture, Layered approach, CRUD, Data Transfer Object (DTO), Command Object, Input Port, Read-Only Query

5.8.2 The "Indirection" Frustration

This section explains the code-navigation cost of using ports and adapters and the flexibility gained in return.

Key terms: indirection, Ports, Adapters, Go to Definition

5.8.3 Mapping Fatigue

This section explains the repetitive mapping cost of keeping a hexagonal architecture’s domain separate from infrastructure and why that boundary should not be abandoned for an unmeasured performance gain.

Key terms: Inside, Outside, Domain, Infrastructure, Database Entity, Mappers, performance hits, leaky code, premature optimization, clarity

5.8.4 The Architect's Decision Matrix

This section gives practical criteria for choosing layered or hexagonal architecture while weighing technical benefits against design complexity and project constraints.

Key terms: Layered Architecture, Hexagonal Architecture, rich business rules, core logic, complexity tax, constraints, technical benefits

5.9 Your "In Action" Mission: Refactoring to Hexagonal

This section invites readers to practice finding a hidden dependency in their own or a teammate’s code, without needing a company codebase.

5.9.1 1. The Hunt: Dig Up Your Own Skeleton

This subsection asks the reader to find places where core business logic directly uses external tools or the outside world.

Key terms: core business logic, leaks, external dependency

5.9.2 2. The Sketch: 5 Minutes on Paper

This section asks the reader to sketch a class’s leaky dependency and the proposed port-and-adapter boundary before changing code.

Key terms: hexagon, leaky dependency arrow, port, adapter, Step 3: The Sketch, boundary, leak logic

5.9.3 3. The Refactor: Steal This Example

The Crypto Portfolio Tracker example shows why hard-coding an external price API into value calculations is fragile and difficult to test.

Key terms: core business logic, CoinGecko, Port, fake adapter, unit test

5.10 Checklist

This checklist prompts readers to recall the chapter’s core ideas and briefly defines a leaky port.

Key terms: Leaky Port, SQL, HTTP types

5.11 Recap

Recaps how hexagonal architecture protects business logic through an independent core, ports, adapters, and inward-pointing dependencies, making the logic easier to test.

Key terms: Hexagonal Architecture, Core Business Logic, Inside vs. Outside, Golden Rule, Ports, Adapters, interfaces, Testability, Fake adapters, entanglement

Where this is used later

Concepts explained in this chapter

← Chapter 4: Thinking in Layers: Separating the 'How' from the 'Why' at Scale Chapter 6: Reliable API Design: Public Contracts and Synchronous Communication →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.