When business logic knows an API’s response shape or a database’s persistence model, external changes can ripple through the core. An adapter contains those details outside the core and connects an external technology to a core-defined port. section 1.0 section 1.1.1
Adapters have two distinct directions of interaction:
- A driving adapter receives an external request or event and calls an input port. A REST controller, for example, translates HTTP requests into commands or queries without owning business logic. section 1.1.1 section 5.5
- A driven adapter implements an output port that the core calls. An API adapter can use an HTTP client to reach an external service; a repository adapter can persist domain state. section 1.1.1 section 8.6
Both kinds depend inward. The core defines contracts in its own terms; it does not depend on concrete adapters. Output adapters translate between port DTOs and infrastructure formats. Repositories are an exception: their ports may work directly with domain entities to persist and reconstitute state. section 1.1.2 section 5.5
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 Java listing pairs core-defined ports with a JPA repository adapter and an external API adapter. section 1.1.1
At an external-service boundary, the adapter owns the other system’s format, protocol, serialization, and mechanics such as retries, timeouts, deduplication, and failure mapping. The application or domain sets the relevant policies; the adapter implements them. section 10.5
Bind adapters to ports in the assembly layer. A handler can then be tested with a mock port, while adapter tests target the translation and external dependency: for example, mock Spring Data for persistence or use MockRestServiceServer for a RestClient adapter. The test technique depends on the collaborator being wrapped. section 6.2.2 section 8.6 section 8.8
The boundary costs extra classes and can make tracing less direct. For simple CRUD or stable systems, that ceremony may not pay off. In a coupled application, migrate gradually: identify domain rules, define ports, move orchestration into handlers, and wrap existing infrastructure before replacing it. section 1.2.6
















