liveBook · Manning

Chapter 3: Building the domain core

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

The introduction argues that WriteFlow’s migration should begin with a framework-independent domain core whose business rules prevent invalid states.

After this chapter you will be able to

What it builds on

Section by section

Introduction

The introduction argues that WriteFlow’s migration should begin with a framework-independent domain core whose business rules prevent invalid states.

Key terms: Phase 1—Extract the domain, business core, domain, business invariants, invalid states, construction time

3.1 What lives inside the domain layer

This section defines what belongs in the domain core, introduces its main DDD building blocks, and explains why domain objects stay behind its boundary.

Key terms: domain layer, business rule, invariant, infrastructure, entities, value objects, aggregates, ArticleId, Title, domain boundary

3.2 Three principles that shape the domain

This section explains why domain design borrows functional ideas and where to prioritize its guiding principles.

Key terms: functional design, immutability, explicit inputs and outputs, return type, purity, encapsulation, completeness, entities, value objects, business invariants

3.3 The Always-Valid Domain Model

The section establishes that domain objects must be valid from the moment they exist and explains how controlled construction enforces that guarantee.

Key terms: Always-Valid Domain Model, Article, business rule, private constructor, factory method, invariants, error

3.3.1 What not to do: Validation after construction

This section explains why validating an Article after construction or in a handler fails to guarantee a valid domain model, and why domain creation should be separated from framework construction.

Key terms: isValid, Article, Application Service, handler, title validation, factory method, invariants, private constructor, persistence and serialization frameworks

3.3.2 The recommended approach: validateThenCreate

This section shows how a private constructor and a validateThenCreate factory make Article creation valid by construction, collect field errors, and keep validation out of the handler.

Key terms: TryExecute pattern, validateThenCreate, private constructor, invariants, Always-Valid Domain Model, Validation, Validation.combine, ap, Seq<DomainError>, Either

3.3.3 An alternative: canBeCreated

This subsection compares separating validation from Article construction with validating in the constructor, and explains why the book favors explicit creation failures.

Key terms: canBeCreated, Command-Query Separation, Article, validateThenCreate, explicit return type, exceptions, Architecture Decision Record

3.3.4 A note on records

Explains why Java records are unsuitable for domain entities whose construction must be controlled by validation, while remaining useful for simpler data types.

Key terms: Java records, canonical constructor, Always-Valid Domain Model, validateThenCreate, @RequiredArgsConstructor(access = AccessLevel.PRIVATE)

3.4 Value objects: Making implicit concepts explicit

This section shows how value objects make domain concepts explicit, enforce their constraints at construction, and avoid the problems of using raw primitive types.

Key terms: Primitive Obsession, value object, constructor validation, type safety, PublicationPeriod, isActiveOn, business rule, Equality by value, Immutability, Java records

3.5 Domain services

This section explains when business rules belong in a domain service, how that differs from application orchestration, and why domain services are simple to test.

Key terms: domain service, application service, aggregates, business rules, existing slugs, persistence boundary, database constraint, consistency guard, pure function, infrastructure dependencies

3.6 Factories

This section explains when to create an entity through its own factory method or a standalone factory, and how to keep construction and validation responsibilities separate.

Key terms: factory method, entity-level factory, standalone factory class, Article.validateThenCreate, private constructor, validation factory, identity generation, dependency injection, handler

3.7 Model identity: Filling the gap

Explains how entities can receive an identity while preserving, or explicitly qualifying, the Always-Valid Domain Model.

Key terms: in-scope identity, UUID, Always-Valid Domain Model, out-of-scope identity, repository, nextIdentity(), aggregate, transient "new" state, Architecture Decision Record, NewArticle

3.8 Two kinds of validation

This section distinguishes input validation from business invariant validation and assigns each validation responsibility to the appropriate layer of a hexagonal application.

Key terms: input validation, syntactic, business invariant validation, semantic, Always-Valid Domain Model, primary adapter, CreateArticleCommand, CreateArticleHandler, Article.validateThenCreate, secondary adapter

3.8.1 Input validation with the Validation monad

This section explains how commands use Validation to check input syntax at the boundary while the domain remains responsible for business rules.

Key terms: Validation, commands, handlers, domain objects, syntax, business rules, CreateArticleCommand.validate(...), Validation monad, private constructor, validate factory method

3.9 Guard clauses

Guard clauses make validation easier to read by returning early for unmet preconditions, while the choice to stop at one failure or collect several depends on the operation.

Key terms: guard clauses, precondition, happy path, fail fast, object creation, invalid states

3.10 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 Chapter 4: The honest hexagon: Use cases, commands, and the case against exceptions →

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.