liveBook · Manning

Chapter 1: Taming complexity with hexagons

What you will learn in chapter 1 of Clean Applications with Hexagonal Architecture

The introduction explains how hard-wired dependencies create accidental complexity and presents hexagonal architecture as a way to contain the effects of change.

After this chapter you will be able to

Section by section

Introduction

The introduction explains how hard-wired dependencies create accidental complexity and presents hexagonal architecture as a way to contain the effects of change.

Key terms: accidental complexity, hard-wiring, Hexagonal Architecture, Ports and Adapters, application core, explicit boundaries, dependencies point inward, replaceable adapters

1.1 What is hexagonal architecture

The section introduces hexagonal architecture as a way to contain complexity by isolating business logic behind core-defined ports and external adapters.

Key terms: accidental complexity, core, infrastructure, hexagon, domain entities, use cases/handlers, input ports, output ports, driving adapters, domain rules

1.1.1 Core concepts: Ports and adapters

This section explains how a hexagonal architecture isolates the business core using ports, adapters, and inward-pointing dependencies.

Key terms: hexagon, core business logic, boundary, ports, Input Ports (Use Cases), Output Ports, adapters, Primary (Driving) Adapters, Secondary (Driven) Adapters, core

1.1.2 The secret sauce: Dependency inversion

This section explains how dependency inversion makes adapters depend on core-defined ports, keeping the core independent of infrastructure and enabling easier testing, replacement, and collaboration.

Key terms: Dependency Inversion Principle, core-defined ports, adapters, ArticleRepository, Testable Core, POJOs, mocked ports, Swappable Adapters, Framework-Agnostic Core, port

1.2 Why hexagonal architecture matters

This section explains how seemingly practical shortcuts can accumulate into architectural decay that constrains a system later.

Key terms: architectural decay, proper boundary, encapsulation, accidental compromises

1.2.1 An uncomfortable truth

The section uses architectural anti-patterns to show how systems become fragile when boundaries are weak, even if their structure looks disciplined.

Key terms: weak boundaries, cost of change, local reasoning, Lasagna, @Entity, @JsonProperty, REST controller, Spaghetti, Ravioli, Spaghetti with Meatballs

1.2.2 The illusion of decoupling

This section shows how weak boundaries create the appearance of decoupling while making code harder to change and reason about.

Key terms: synthetic interface, implementing layer, calling layer, dependency direction, weak boundaries, architectural drift, responsibilities, models, explicit boundaries, controlled dependency direction

1.2.3 Less of a revelation, more of a confirmation

The section argues that hexagonal architecture matters because deliberately owned boundaries protect business logic from infrastructure and the gradual erosion that makes systems hard to change.

Key terms: boundaries, boundary ownership, dependency inversion, domain, core business logic, frameworks, transport models, domain models, bad boundaries

1.2.4 A pattern that changed everything

A cross-domain migration shows why interfaces alone did not make an Article service reusable, and how a core-defined boundary did.

Key terms: ArticleRepository, REST response shapes, Spring @Transactional, core sovereignty, ports, adapters, CreateArticleUseCase

1.2.5 Comparison with other patterns

This section places hexagonal architecture among inward-dependency patterns and explains why its ports-and-adapters vocabulary is useful for integrations.

Key terms: dependencies should point inward, ports/adapters, integration point

1.2.6 When NOT to use hexagonal architecture

This section weighs when hexagonal architecture is worth its costs and explains how to adopt it incrementally and make a practical case for it.

Key terms: ports, adapters, handlers, fake hexagonal, tracing overhead, traditional layers, strict architectural isolation, convention-over-configuration, bounded context, facade adapters

1.3 How hexagonal architecture works

Traces an article-creation request through a hexagonal application, showing where business rules, infrastructure, and error handling belong.

Key terms: ArticleController, CreateArticleCommand, Input Port, CreateArticleUseCase, CreateArticleHandler, Domain, invariants, Article, validateThenCreate, Always-Valid Domain Model

1.3.1 Key Takeaways

This section summarizes how requests move through a hexagon and how its boundaries support isolated testing, replaceable adapters, and explicit failures.

Key terms: inward dependencies, clear boundaries, port, core, adapters, testable core, CreateArticleHandler, mocks, swappable infrastructure, configuration

1.4 What you need to get started

This section sets out the experience the reader needs and the Java tools used to build and verify the book’s hexagonal applications.

Key terms: OOP, layered architectures, SOLID principles, unit testing, Spring Boot, functional programming, Java 21+, Spring Boot 3.x/4.x, Maven, multi-module structure

1.5 How this book teaches hexagonal architecture

The section previews a pragmatic, test-backed learning path built around an evolving Article/Author application, from a hexagonal core to distributed systems.

1.6 Summary

Where this is used later

Concepts explained in this chapter

Chapter 2: WriteFlow's wake-up call: When good architecture intentions aren't enough →

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.