hexagonal-architecture-layers-java

Enforce clean architecture boundaries by organizing your Java application into three layers: Domain (pure business logic with no framework dependencies), Application (use cases and ports that orchestrate domain logic), and Infrastructure (adapters connecting controllers, repositories, and external services). This separation keeps domain logic decoupled from frameworks and persistence concerns.

Hexagonal architecture, also called ports-and-adapters, structures applications around a pure domain core with clearly defined entry and exit points. Unlike traditional layered architecture, it emphasizes bidirectional dependency flow toward the domain, uses ports as interfaces for domain interactions, and allows multiple adapters per port for flexibility and testability.

Structure your Java application by identifying Domain, Application, and Infrastructure boundaries. Define your Domain model free of framework annotations, create Application layer ports that abstract I/O operations, then implement Infrastructure adapters for Spring components, controllers, and repositories. This ensures domain purity and decoupled dependencies.

Yes, hexagonal architecture applies to Java services organized with Spring-based components. You can refactor existing applications by extracting domain logic into framework-free classes, defining ports as Spring interfaces, and implementing adapters for controllers and repositories. This approach suits both initial structuring and refactoring for modularity.

Common mistakes include allowing framework annotations in the Domain layer, creating ports that leak infrastructure details, and violating dependency direction by having adapters depend on the domain outward. Ensure domain remains pure, ports define clear contracts, and all dependencies point inward toward the domain core.

Define ports in the Application layer as interfaces representing specific I/O needs (e.g., repository ports, notification ports). In the Infrastructure layer, implement multiple adapters satisfying each port contract—different database adapters, message queue adapters, or external service clients—allowing you to swap implementations without affecting domain or application logic.