When business logic depends directly on a database, framework, or transport model, an infrastructure change can ripple through the core. A port makes that boundary explicit: it is an interface defined by the application core for an interaction with the outside world. Adapters connect external technologies to that interface, while dependencies point inward. section 1.0 section 1.1.1
Ports have two roles:
- An input port declares what the application can do. A driving adapter, such as a REST controller or message consumer, calls it; a core handler implements it. section 1.1.1 section 2.3
- An output port declares what the core needs, such as persistence or a call to an external service. A driven adapter implements the interface and hides the technology-specific details. section 1.1.1
A request can enter through a driving adapter and input port, be processed by a handler, and leave through an output port to a driven adapter. The handler depends on the core-defined interface, not on a concrete repository or client. Port signatures should speak domain language rather than expose HTTP or infrastructure details; an interface alone does not prevent those details from leaking into the core. section 1.6 section 2.3 section 1.2.4
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 and implementations show both sides of the boundary: the handler implements the input port, while repository and service adapters implement output ports. section 1.1.1
Article creation
CreateArticleUseCase exposes article creation to a driving adapter. CreateArticleHandler implements the use case and depends on ArticleRepository, an output port. A JpaArticleRepositoryAdapter implements that repository contract and contains the JPA details. A REST adapter and a Kafka consumer can call the same use case without changing its port. section 1.1.1 section 2.3
For an incremental migration, identify domain rules, define ports around current behavior, move orchestration into handlers, and wrap existing controllers and repositories as adapters. Test handlers with mocked ports and enforce boundaries with architectural tests. Ports and adapters add classes and tracing overhead, so the isolation may not justify the ceremony for a simple prototype or stable CRUD application. section 1.1 section 1.2.6 section 2.5





