When a handler calls a database or external API directly, infrastructure choices spread into business logic. A driven adapter, also called an output or secondary adapter, keeps those details outside the application core. The core defines an output port for what it needs; the adapter implements that port and translates the request into an interaction with an external system. section 1.1 section 5.2.1
Control flows outward when the handler calls the port, but source dependencies point inward: both the handler and the adapter depend on the core-owned interface. A driving adapter works in the opposite direction of interaction, receiving an external request and invoking an input port. section 1.1.1 section 2.2
Keep the boundary explicit:
- Name the port for the core’s need, such as ArticleRepository or AuthorLookupOutputPort, rather than for a technology such as JPA or REST. section 2.3.2
- Put queries, API calls, serialization, data mapping, and infrastructure-error translation in the adapter. Keep business decisions and domain invariants in the handler or domain. section 2.3.2 section 5.2.1
- Inject the concrete adapter at assembly time. Replacing it with an in-memory implementation or another infrastructure implementation should not require changes inside the core. section 5.2 section 5.2.1
Saving an article
CreateArticleHandler depends on the ArticleRepository interface and calls save after validating and creating an Article. JpaArticleRepositoryAdapter implements the interface and hides the JPA details. An in-memory repository can fulfill the same port for development or tests. section 1.1.1 section 1.3
Listing 1.1 Relating these pieces in code
public interface CreateArticleUseCase { // #A
Either<Error, Void> execute(CreateArticleCommand command);
}
public interface ArticleRepository {
Either<Error, Void> save(Article article); // #B
}
public interface GetAuthorBiblioOutputPort { // #C
Either<Error, BiblioDTO> biblioForAuthor(String author);
}
public class CreateArticleHandler implements
➥ CreateArticleUseCase { // #D
private final ArticleRepository repository;
// ... orchestration logic
}
public class JpaArticleRepositoryAdapter
➥ implements ArticleRepository { // #E
// ... JPA/database details hidden here
}
public class AuthorBiblioAdapter implements
➥ GetAuthorBiblioOutputPort { // #F
// ... call external API/service
}
The interfaces, handler, and concrete adapters show which classes own the contracts and which implement them. section 1.1.1
Calling an author service
An outbound adapter implements an author-validation port, calls the service’s published API, and maps its response into the port’s DTO. It also maps failures into local errors, such as AuthorNotFound or DependencyUnavailable. The handler sees the local contract, not the service’s model. section 11.4
For synchronous calls, bound the wait and retry only transient failures. Retry an ambiguous state-changing call only if the contract guarantees deduplication for the same idempotency key or an authoritative check confirms the first attempt had no effect; otherwise reconcile the uncertain outcome. Boundary checks can also enforce inward dependencies and catch infrastructure leakage. section 11.9 section 9.5


