Hexagonal Architecture (Ports & Adapters)¶

Category: Architecture Tags: hexagonal, clean-architecture, java, ports-adapters, kubernetes

Overview¶

Hexagonal Architecture, or Ports and Adapters, separates the core logic from the infrastructure, allowing independent evolution of business logic and external systems.

What It Is¶

Core business logic in the center
Ports define interfaces the core needs
Adapters are implementations like REST, DB, etc.

Why Use It¶

High testability and decoupling
External tech changes don’t affect the core
Suitable for systems under frequent infrastructure change

When To Use It¶

Domain-driven systems
Projects with high focus on maintainability and testing
Complex integrations

Implementation Examples¶

Code Example (Java)¶

// Port interface
public interface UserRepository {
    User findById(Long id);
}

// Adapter implementation
@Repository
public class JpaUserRepository implements UserRepository {
    // implementation using Spring Data JPA
}

Infra Example (Kubernetes)¶

apiVersion: apps/v1
kind: Deployment
metadata:
  name: user-service
spec:
  replicas: 2
  selector:
    matchLabels:
      app: user-service
  template:
    metadata:
      labels:
        app: user-service
    spec:
      containers:
      - name: user-service
        image: myregistry/hex-user-service:latest

Key Concepts Summary¶

Clean separation of business and tech
Ports are interfaces; adapters are tech-specific code
Encourages clean testing and modular design

Best Practices / Tips¶

Put business rules in the center
Use dependency inversion — core should not depend on adapters
Avoid bloated adapter layers

Common Issues / Troubleshooting¶

Problem 1: Confusion between layers¶

Cause: Misuse of ports vs adapters
Solution: Strict interface contracts and layered package structure

Problem 2: Over-architecture for small projects¶

Cause: Too much separation for basic needs
Solution: Use only where complexity demands it

References / Further Reading¶

https://alistair.cockburn.us/hexagonal-architecture/
https://reflectoring.io/spring-hexagonal/