hexagonal-architecture-layers-java_skill

Overview

This skill codifies strict hexagonal layering for Java services: Domain, Application, and Infrastructure with clear, enforced boundaries. It shows how to keep domain logic pure, orchestrate use cases in the application layer, and adapt frameworks in infrastructure. Use it to design new services or to refactor Spring apps toward clean architecture.

How this skill works

The skill inspects service structure and prescribes where code belongs: domain objects and business rules stay free of annotations and I/O. Application defines input ports (use cases) and output ports (interfaces) that orchestrate domain operations. Infrastructure implements ports and wires adapters such as controllers, repositories, and external clients.

When to use it

• Designing a new Java service with testable, framework-agnostic domain logic
• Refactoring Spring or monolithic code to isolate business rules from frameworks
• Supporting multiple adapters (REST, messaging, gRPC) without mixing concerns
• Switching persistence technologies (JPA, Mongo, JDBC) behind a port interface
• Enforcing module boundaries and dependency direction in a multi-module build

Best practices

• Keep domain classes free of framework imports, annotations, and I/O
• Express all business operations as use cases (input ports) in the application layer
• Define output ports for side effects (repositories, message publishers, external clients) and implement them in infrastructure
• Wire adapters only at composition time (configuration), not inside domain or application classes
• Write tests against ports and services; mock only infrastructure implementations

Example use cases

• PlaceOrder use case: application service generates ID, builds domain Order, calls OrderRepositoryPort to persist
• Add a messaging adapter: implement a PublisherPort in infrastructure and inject into application service
• Refactor JPA entities: map domain objects to persistence entities in an adapter, keep domain unchanged
• Support multiple data stores: create separate adapters implementing the same repository port (JPA, Mongo) and switch by wiring