liveBook · Manning

Port

As explained in Clean Applications with Hexagonal Architecture

An application boundary interface through which external actors or technologies interact with the application core.

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

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains input and output responsibilities, dependency direction, Java interfaces, and incremental migration steps.
Examples
Uses article creation, a JPA repository adapter, and REST and Kafka entry points to illustrate port roles and reuse.
What you can do after
Apply ports by extracting core interfaces, refactoring handlers, wrapping existing infrastructure, and testing boundaries.
How it connects
Connects hexagonal architecture with adapters, dependency inversion, handlers, and domain models.

Also explained in

Compare how 6 books explain port →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.