Chapter 1: Taming complexity with hexagons
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
- Accidental Complexity from Hard-Wiring. Explain what the section calls accidental complexity and how direct coupling to technologies and other components makes changes ripple through a codebase.
- Inward Dependencies and Explicit Boundaries. Explain the section’s central principle of hexagonal architecture: the core defines what it does and needs, while external technologies connect through replaceable adapters behind explicit boundaries.
- Core ports and external adapters. Describe what belongs in the hexagonal core, distinguish input from output ports and driving from driven adapters, and explain the direction of dependencies.
- Business core and boundary. Explain what belongs inside the hexagon and why its boundary separates business logic from external technologies.
- Input and output ports. Distinguish input ports from output ports by what each declares about the application.
- Driving and driven adapters. Distinguish driving adapters from driven adapters by how they interact with ports and the core.
- Inward dependency direction. Explain which way dependencies point between the core, its interfaces, and adapter implementations.
- Inward dependency direction. Explain how hexagonal architecture reverses the dependency direction of traditional layers: the core defines ports, and external adapters conform to them.
- Accumulated architectural compromises. Explain how individually reasonable shortcuts can gradually weaken an architecture and why their cost may become apparent only later.
- Weak Boundaries Behind Fragility. Explain why an architecture can look orderly yet become increasingly difficult to change.
- Leaking Layered Architecture. Describe the Lasagna anti-pattern and how one object can carry concerns across apparent layers.
- Synthetic interfaces and false decoupling. Explain why an interface that mirrors one implementation does not necessarily decouple a system, especially when the implementing layer owns it rather than the calling layer.
- Weak boundaries and architectural drift. Describe how weak boundaries let responsibilities, models, and behavior drift, despite a codebase still appearing layered or modular.
- Cognitive cost and durable boundaries. Explain why poor architecture makes ordinary changes mentally taxing and what qualities make architectural boundaries useful.
- Deliberate protection of the domain. Explain why hexagonal architecture treats boundaries as deliberate design decisions and what those boundaries are meant to protect.
- Core sovereignty for reuse. Describe the boundary the author drew around business logic and how it allowed the same use-case port to work across domains.
- Inward dependencies and integration points. Explain that hexagonal architecture shares an inward-pointing dependency principle with related patterns, but uses ports and adapters to make different integration points explicit and swappable.
- Costs of Architectural Isolation. Explain the practical costs of hexagonal architecture: more classes up front, a learning curve that can leave business logic in adapters, and less direct debugging paths.
- Choosing Architecture by Context. Distinguish situations where hexagonal architecture's isolation may pay off from stable or tightly integrated applications where traditional layers may be more pragmatic.
- Incremental Migration Path. Describe the section's small-start migration path for a coupled layered system, including temporary adapters and parallel operation rather than a wholesale rewrite.
- Article creation request flow. Trace how an HTTP article-creation request becomes a command, enters through an input port, and is orchestrated by a handler.
- Domain validity boundary. Explain where article business rules are enforced and how the Article entity is kept valid.
- Output ports and adapters. Describe how the handler fetches authors and saves articles without depending on particular external technologies.
- Request flow and boundaries. Trace a request inward through a port to the core, outward through another port, and back. Explain that dependencies point toward the core and adapters do not communicate directly with each other.
- Application stack and boundaries. Describe how the section positions Java, Spring Boot, and Maven in the application setup, including what remains independent of Spring.
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.
- Accidental Complexity from Hard-Wiring: Explain what the section calls accidental complexity and how direct coupling to technologies and other components makes changes ripple through a codebase.
Why it matters: Recognizing where change spreads helps explain why architectural boundaries are worth maintaining. - Inward Dependencies and Explicit Boundaries: Explain the section’s central principle of hexagonal architecture: the core defines what it does and needs, while external technologies connect through replaceable adapters behind explicit boundaries.
Why it matters: This principle gives the reader a way to reason about where external technology belongs when an application changes.
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.
- Contained change through boundaries: Explain how mixing business rules with frameworks and infrastructure makes changes spread through a codebase, and why isolating the core helps contain that impact.
Why it matters: This is the problem the hexagonal boundary is meant to address. - Core ports and external adapters: Describe what belongs in the hexagonal core, distinguish input from output ports and driving from driven adapters, and explain the direction of dependencies.
Why it matters: These boundaries let the business core remain independent of particular interfaces and technologies. - Incremental extraction of the core: Trace the retrofit sequence described for an existing system, from finding domain rules through defining ports and refactoring handlers to swapping adapters and testing against mocked ports.
Why it matters: The section presents hexagonal architecture as a practical retrofit, not only a design for new systems.
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.
- Business core and boundary: Explain what belongs inside the hexagon and why its boundary separates business logic from external technologies.
Why it matters: The boundary helps keep business rules independent of particular frameworks and services. - Input and output ports: Distinguish input ports from output ports by what each declares about the application.
Why it matters: This distinction separates the application's offered capabilities from its external needs. - Driving and driven adapters: Distinguish driving adapters from driven adapters by how they interact with ports and the core.
Why it matters: The distinction shows where external requests enter and where the core obtains outside capabilities. - Inward dependency direction: Explain which way dependencies point between the core, its interfaces, and adapter implementations.
Why it matters: Inward dependencies allow external implementations to change without making the core depend on them.
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.
- Inward dependency direction: Explain how hexagonal architecture reverses the dependency direction of traditional layers: the core defines ports, and external adapters conform to them.
Why it matters: This dependency direction is what prevents infrastructure choices from becoming core requirements. - Testable business logic: Explain why a core that uses ports can be tested with mocked dependencies without starting the framework or a database.
Why it matters: Tests can exercise core behavior without waiting for infrastructure to start. - Replaceable external technology: Describe how an adapter can be replaced while retaining the same port, and how that separation keeps domain logic independent of framework choices.
Why it matters: Infrastructure can evolve without forcing a rewrite of business rules. - Explicit team contracts: Explain how ports provide explicit APIs that let teams work on boundary components independently.
Why it matters: An agreed boundary lets separate teams make progress without tightly coupling their implementations.
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.
- Accumulated architectural compromises: Explain how individually reasonable shortcuts can gradually weaken an architecture and why their cost may become apparent only later.
Why it matters: It helps explain why protecting boundaries matters even when a shortcut seems harmless today.
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.
- Weak Boundaries Behind Fragility: Explain why an architecture can look orderly yet become increasingly difficult to change.
Why it matters: A neat-looking design is not enough if changes still ripple across the system. - Leaking Layered Architecture: Describe the Lasagna anti-pattern and how one object can carry concerns across apparent layers.
Why it matters: This example makes it possible to spot a boundary failure even when the layers themselves are visible. - Other Architectural Anti Patterns: Distinguish Spaghetti, Ravioli, and Spaghetti with Meatballs by the failure each describes.
Why it matters: These distinctions show that both visible disorder and excessive structure can undermine a design.
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.
- Synthetic interfaces and false decoupling: Explain why an interface that mirrors one implementation does not necessarily decouple a system, especially when the implementing layer owns it rather than the calling layer.
Why it matters: It helps you spot abstractions that look protective but leave the core exposed. - Weak boundaries and architectural drift: Describe how weak boundaries let responsibilities, models, and behavior drift, despite a codebase still appearing layered or modular.
Why it matters: It directs attention from isolated code smells to the structural problem they may share. - Cognitive cost and durable boundaries: Explain why poor architecture makes ordinary changes mentally taxing and what qualities make architectural boundaries useful.
Why it matters: Reliable boundaries make changes easier to reason about without demanding architectural purity.
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.
- Deliberate protection of the domain: Explain why hexagonal architecture treats boundaries as deliberate design decisions and what those boundaries are meant to protect.
Why it matters: Deliberate boundaries help the business core remain clear when surrounding technologies change. - Practical cost of weak boundaries: Describe how seemingly practical boundary compromises can make an application increasingly difficult to change.
Why it matters: It explains why boundary problems may be costly long before they look like obvious architectural failures.
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.
- Limits of interface-based reuse: Explain why the Article publishing components failed to transfer to a compliance-heavy domain despite using interfaces.
Why it matters: An interface alone does not keep external assumptions out of the code behind it. - Core sovereignty for reuse: Describe the boundary the author drew around business logic and how it allowed the same use-case port to work across domains.
Why it matters: Keeping external details behind adapters lets the business core survive a change of environment.
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.
- Inward dependencies and integration points: Explain that hexagonal architecture shares an inward-pointing dependency principle with related patterns, but uses ports and adapters to make different integration points explicit and swappable.
Why it matters: It clarifies what hexagonal architecture shares with related patterns and why this book uses its terminology.
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.
- Costs of Architectural Isolation: Explain the practical costs of hexagonal architecture: more classes up front, a learning curve that can leave business logic in adapters, and less direct debugging paths.
Why it matters: These costs help you judge whether the architecture will solve more problems than it creates. - Choosing Architecture by Context: Distinguish situations where hexagonal architecture's isolation may pay off from stable or tightly integrated applications where traditional layers may be more pragmatic.
Why it matters: The point is to choose useful boundaries, not to apply hexagonal architecture everywhere. - Incremental Migration Path: Describe the section's small-start migration path for a coupled layered system, including temporary adapters and parallel operation rather than a wholesale rewrite.
Why it matters: A bounded pilot makes an architectural change possible without betting the running system on one rewrite. - Evidence for Stakeholder Buy-In: Describe how to make the case for a hexagonal pilot using evidence suited to developers, managers, and skeptics.
Why it matters: A pilot gives different stakeholders something concrete to evaluate before committing to a broader change.
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.
- Article creation request flow: Trace how an HTTP article-creation request becomes a command, enters through an input port, and is orchestrated by a handler.
Why it matters: This path shows how an external request reaches business behavior without carrying HTTP concerns into the core. - Domain validity boundary: Explain where article business rules are enforced and how the Article entity is kept valid.
Why it matters: Keeping validity in the domain prevents an Article from existing in an invalid state regardless of its entry point. - Output ports and adapters: Describe how the handler fetches authors and saves articles without depending on particular external technologies.
Why it matters: The application can change a database or external-service implementation without rewriting its business workflow. - Explicit errors at the boundary: Trace how a failed creation step is returned and translated into an HTTP response.
Why it matters: Explicit results let the core report failures without taking responsibility for HTTP responses.
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.
- Request flow and boundaries: Trace a request inward through a port to the core, outward through another port, and back. Explain that dependencies point toward the core and adapters do not communicate directly with each other.
Why it matters: This is the mental model the section says applies to every hexagonal operation. - Isolated core and replaceable adapters: Describe how the core can be tested with mocks without a framework or database, and how adapters can be replaced by changing configuration.
Why it matters: These are practical benefits of keeping the core separate from its adapters. - Explicitly handled failures: State that failures should be typed and handled rather than left as hidden exceptions.
Why it matters: Explicit failures make the outcome visible rather than leaving it hidden in an exception path.
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.
- Starting experience and expectations: State the experience the book assumes and distinguish it from topics taught as the application is built.
Why it matters: It clarifies what you can bring to the book and what you can learn along the way. - Application stack and boundaries: Describe how the section positions Java, Spring Boot, and Maven in the application setup, including what remains independent of Spring.
Why it matters: The setup supports the architecture without making the application core depend on its framework. - Supporting library roles: Describe the distinct purposes of the supporting libraries for error handling, code generation, and testing.
Why it matters: These roles show which tools address application code, boundary mapping, and verification rather than treating the tool list as one undifferentiated stack.
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
- The WriteFlow migration: A step-by-step map (chapter 2) · Expands the migration sequence sketched here into a step-by-step map.
- What lives inside the domain layer (chapter 3) · Identifies what belongs in the domain layer.
- Phase 2: Define the ports (chapter 2) · Defines the ports during the WriteFlow migration.
- What an input adapter is (and is not) (chapter 5) · Develops the role of input adapters.
- What an output adapter is (and is not) (chapter 5) · Develops the role of output adapters.
- Dependency rules: Who may import whom (chapter 7) · Enforces permitted dependency directions.
- Handlers: Mock ports, verify interactions (chapter 8) · Testing handlers by mocking their ports.
- Implementing an external service adapter (chapter 5) · Implementing an external service adapter behind a port.
Concepts explained in this chapter
- hexagonal architectureAn application design pattern that isolates the application core behind ports and connects external technologies through adapters.
- adapterAn adapter that connects an application to an external service through an API.
- portAn application boundary interface through which external actors or technologies interact with the application core.
- application coreThe central part of an application containing its domain and application logic while remaining independent of external technologies.
- dependency inversionA design principle stating that high-level and low-level components should depend on abstractions rather than concrete implementation details.
- outbound portAn application-facing boundary that declares a service the application requires from an external system.
- primary portAn interface exposing an application operation that an external caller can invoke.
- driven adapterAn adapter that implements an output port and translates application requests into interactions with an external system.
- EitherEither is a functional data type representing one of two alternatives, commonly a failure value or a successful result.
- system boundaryA structural separation that defines permitted responsibilities and dependencies between parts of a software system.
- REST controllerAn adapter that accepts REST requests and translates them into calls to application input ports.
- accidental complexityThe additional difficulty and disorder introduced by design choices, implementation shortcuts, and unnecessary coupling rather than by the problem domain itself.
- always-valid domain modelA domain-modeling approach that prevents objects from representing states that violate their invariants.
- commandA command object encapsulates data representing a requested application operation.
- ArchUnitArchUnit is a Java library for expressing and testing architectural constraints in code.
- application serviceA service that coordinates an application use case and its domain operations without containing infrastructure concerns.
- domain modelA software representation of the concepts, relationships, and rules of a business domain.
- invariantA condition that must remain true for a domain object or business state to be valid.
- business logicThe rules and processing that express an application's business behavior independently of external technologies.
- driving adapterA primary adapter translates an external trigger into a call to an application input port.
- handlerA handler is an application component that processes a request and coordinates the interactions needed to fulfill it.
- dependency directionA constraint specifying which software components or layers are permitted to depend on one another.
- entityA domain object with an identity whose state and invariants are governed by domain rules.
- use caseA use case is an application operation that coordinates domain rules to accomplish a specific user or system goal.
- dependency injectionDependency injection is a design technique in which an object's dependencies are supplied by external configuration or infrastructure.
- architectural testingArchitectural testing automatically checks whether a codebase conforms to specified structural and dependency rules.
- validation resultValidation is a Vavr value type for applicatively accumulating validation errors or producing a valid value.
- queryA query is a request that retrieves information without changing application or domain state.
- unit testA testing technique that verifies small units of software in isolation from their dependencies.
- error typeAn error represented by a distinct type so that its category and handling behavior are explicit.
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.
