Hexagonal Architecture

Architecture

BINDING RULES FOR ALL AI AGENTS: The patterns documented here are MANDATORY. Every new class MUST follow the layer placement rules. Every new adapter MUST implement the correct port interface. Violations of dependency direction (domain depending on infrastructure, use cases depending on adapters) are NEVER acceptable. Cross-cutting concerns (caching, metrics, logging) MUST be implemented as decorator adapters via the Chain of Responsibility pattern.

Decisions: every architecturally significant choice (port shape, adapter technology, transaction strategy, outbox topology, layer boundary change) MUST be captured as an ADR per adr.md before merging. Default template = MADR. Default location = docs/adr/. Reviewing existing accepted ADRs is a prerequisite before proposing a conflicting design.

This project follows Hexagonal Architecture (Ports and Adapters) with a Gradle multi-module layout. The goal is to isolate the domain and application logic from frameworks and I/O while making adapters replaceable.

Use Cases in the Application Layer (not the Domain)

Definition

A Use Case is an application-level service that orchestrates the Domain Model to fulfill a user or system intent (e.g., CreateInvoice, PayInvoice). It coordinates domain objects and ports, applies application policies (transactions, security, idempotency, retries), and translates between the outside world and the domain—without embedding technical details (DB/HTTP/Kafka) or the business rules themselves.

Why the application layer?

• Separation of concerns: keeps business rules (Entities, Value Objects, Domain Services, Domain Events) pure in the Domain, while workflow/orchestration lives in Application.

• Dependency rule: Application depends inward on Domain; Infrastructure depends on Application. This prevents framework/I/O concerns from leaking into Domain.

• Testability: Use cases are thin, technology-agnostic coordinators—easy to unit test with port fakes/mocks.

• Policy placement: Transactions, authorization, idempotency, saga/compensation are application policies, not domain rules.

Responsibilities of a Use Case

Validate and normalize scenario inputs (beyond low-level DTO validation).

Load aggregates via outbound ports (e.g., InvoiceRepository), invoke domain behavior, and persist changes.

Publish domain events via an application port (e.g., DomainEventPublisher).

Enforce application policies (transaction boundaries, idempotency keys, security checks).

Expose an inbound port (interface) consumed by entry points (REST, messaging, CLI).

Non-responsibilities (anti-patterns)

❌ Implementing business rules that belong to the Domain (that’s for entities/domain services).

❌ Calling frameworks directly (no JDBC/JPA/Kafka/WebClient here).

❌ Depending on framework annotations or types (keep it POJO/record).

Typical dependency flow:

1
Entry Point (REST/Kafka) -> Inbound Port (Use Case Interface)
2
Use Case (Application)   -> Domain Model (Entities/VOs/Domain Services)
3
Use Case                 -> Outbound Ports (Repository/EventPublisher)
4
Infrastructure           -> Implements Outbound Ports & hosts Entry Points

Port placement note

Repositories can be defined either in Domain (pure, ubiquitous language) or Application (pragmatic hexagonal). In both variants, Use Cases remain in Application.

One-liner for your README

Use cases live in the Application layer: they orchestrate domain behavior, apply application policies, and talk to the outside world through ports—keeping the Domain pure and the Infrastructure replaceable.

Modules in this repository

• domain: pure domain model and enums.
• application: use cases and ports (inbound/outbound). Depends on domain only.
• infrastructure
  • entry-points
    • rest-controller: exposes HTTP endpoints; maps requests/responses; handlers; filters and others web or rest apis configs
    • graphql-controller: exposes GraphQL schema and resolvers; handles queries and mutations.
    • webhook-controller: handles incoming webhooks from external systems, providing endpoints for third-party integrations.
    • scheduler-task: executes periodic background tasks and jobs using Spring Scheduling or similar.
    • kafka-consumer: place for inbound messages if needed (currently stub module).
  • driven-adapters
    • jdbc-repository: MyBatis-based persistence for invoices.
    • kafka-producer: publishes domain events to Kafka.
• bootstrap: Spring Boot application, wiring of beans and configuration.

Dependency rules

• domain: no dependencies on any other module.
• application → domain (only).
• infrastructure (entry/driven) → application and domain as needed.
• bootstrap → application + infrastructure to wire everything.
• Never depend inward on infrastructure from domain/application.

Key packages (examples)

• your.base.package.domain: Invoice, value objects, enums.
• your.base.package.usecase: InvoiceUseCase and inbound/outbound ports.
• your.base.package.infrastructure.entry.points.rest.controller: controllers, requests, responses, mappers.
• your.base.package.infrastructure.entry.points.graphql.controller: resolvers, schema, mappers.
• your.base.package.infrastructure.entry.points.webhook.controller: webhook handlers and DTOs.
• your.base.package.infrastructure.entry.points.scheduler.task: task definitions and scheduling logic.
• your.base.package.infrastructure.driven.adapters.jdbc: MyBatis config, repository, entities, mappers.
• your.base.package.infrastructure.driven.adapters.kafka: publishers, message models.
• your.base.package.config (bootstrap): bean configuration for use cases, adapters.

Data flow (example: Create Invoice)

1. REST/GraphQL/Webhook receives request DTO or Scheduler triggers a task.
2. Entry point validates and maps DTO or task parameters to domain model/commands.
3. Entry point calls inbound port (e.g., CreateInvoicePort).
4. Use case applies business rules; calls outbound ports inside a single TX:
   • InvoiceRepositoryPort to persist the aggregate.
   • OutboxRepositoryPort + OutboxEventFactory to enqueue the domain event row (NO broker call).
5. Outbound adapters map domain to tech-specific structures (e.g. InvoiceJdbcEntity), handle I/O. The SDK dispatcher publishes outbox rows asynchronously via MessagePublisherPort.
6. Use case returns domain model; entry point maps it to response DTO (if applicable).

Transactions

• DO NOT place @Transactional directly in use cases (application module). Instead, define a Transaction abstraction (port) in the application layer and implement it in infrastructure.

• This keeps the application layer free from Spring/framework annotations.

• Use functional interfaces for transaction boundaries:

  1
  // Application layer
  2
  fun interface TransactionPort<R> {
  3
      fun run(callback: TransactionCallbackPort<R>): R
  4
  }
  5
  
  6
  fun interface TransactionCallbackPort<R> {
  7
      fun call(): R
  8
  }
  9
  
  10
  // Infrastructure layer
  11
  @Component
  12
  class JdbcTransaction<R> : TransactionPort<R> {
  13
      @Transactional(propagation = Propagation.REQUIRED, rollbackFor = [Exception::class])
  14
      override fun run(callback: TransactionCallbackPort<R>): R {
  15
          return callback.call()
  16
      }
  17
  }
  18
  
  19
  // Use case usage
  20
  class CreateOrganizationUseCase(
  21
      private val transaction: TransactionPort<Organization>,
  22
      // other dependencies
  23
  ) : CreateOrganizationPort {
  24
      override fun execute(command: CreateOrganizationCommand): Organization {
  25
          return transaction.run {
  26
              // All operations here are transactional
  27
              val org = repository.save(command.toOrganization())
  28
              publisher.publishCreated(org)
  29
              return@run org
  30
          }
  31
      }
  32
  }

  Java:

  1
  // Application layer
  2
  @FunctionalInterface
  3
  public interface TransactionPort<R> {
  4
      R run(TransactionCallbackPort<R> callback);
  5
  }
  6
  
  7
  @FunctionalInterface
  8
  public interface TransactionCallbackPort<R> {
  9
      R call();
  10
  }
  11
  
  12
  // Infrastructure layer
  13
  @Component
  14
  public class JdbcTransaction<R> implements TransactionPort<R> {
  15
      @Transactional(propagation = Propagation.REQUIRED, rollbackFor = Exception.class)
  16
      @Override
  17
      public R run(TransactionCallbackPort<R> callback) {
  18
          return callback.call();
  19
      }
  20
  }
  21
  
  22
  // Use case usage
  23
  public class CreateOrganizationUseCase implements CreateOrganizationPort {
  24
  
  25
      private final TransactionPort<Organization> transaction;
  26
      // other dependencies
  27
  
  28
      public CreateOrganizationUseCase(TransactionPort<Organization> transaction /* other deps */) {
  29
          this.transaction = transaction;
  30
      }
  31
  
  32
      @Override
  33
      public Organization execute(CreateOrganizationCommand command) {
  34
          return transaction.run(() -> {
  35
              // All operations here are transactional
  36
              Organization org = repository.save(command.toOrganization());
  37
              publisher.publishCreated(org);
  38
              return org;
  39
          });
  40
      }
  41
  }

• Rollback configuration: Use rollbackFor = [Exception::class] to ensure all exceptions trigger rollback, not just checked exceptions.

Mapping guidelines

• Keep dedicated mappers per boundary:
  • REST/GraphQL mappers: domain ↔ request/response.
  • JDBC mapper: domain ↔ entity and MyBatis mapping.
  • Kafka mapper: domain ↔ Kafka payload.
• No business logic in mappers.

Persistence (Hibernate, MyBatis)

• Entities reflect table columns; use explicit column mapping.
• Keep SQL in mapper XML if queries become complex; avoid SELECT *.
• Liquibase manages schema: add a new changeSet per change using timestamped filenames.

Messaging & Transactional Outbox Pattern

Source of truth: messaging.md. This section is a thin pointer; do not duplicate.

Hard rules (enforced by ArchUnit — see §ArchUnit below):

1. Use cases NEVER call a broker SDK (KafkaTemplate, RabbitTemplate, SqsClient, etc.) and NEVER inject MessagePublisherPort or any domain-specific publisher port (XxxPublisherPort). They inject only OutboxRepositoryPort + OutboxEventFactory (and Transaction for the boundary).
2. Use cases publish via outbox-only. The business write and the outbox insert happen in one local transaction. There is no “fast path”, no “publish first, outbox on failure” fallback — both are dual-write back doors.
3. A separate dispatcher (SendOutboxMessagesUseCase from codehuntersio-sdk-event-messaging) reads the outbox, publishes via MessagePublisherPort, and retries with exponential backoff under a per-service @SchedulerLock. See messaging.md §5 Claim-Based Dispatch.
4. Topology stays outside microservice code — no @Bean Queue / Exchange / Binding / NewTopic. See messaging.md §9.
5. Consumers MUST be idempotent. See messaging.md §7.

Canonical use-case shape (Kotlin):

1
class CreateOrganizationUseCase(
2
    private val transaction: TransactionPort,
3
    private val organizations: OrganizationRepositoryPort,
4
    private val outbox: OutboxRepositoryPort,
5
    private val events: OutboxEventFactory,
6
) : CreateOrganizationPort {
7

8
    override fun execute(command: CreateOrganizationCommand): Organization =
9
        transaction.run {
10
            val org = organizations.save(command.toOrganization())
11
            outbox.save(events.create(
12
                topic = "platform.organizations",
13
                traceId = command.traceId,
14
                aggregate = org.id.toString(),
15
                eventName = "OrganizationCreated",
16
                eventType = EventTypes.EVENT,
17
                payload = OrganizationCreatedPayload.from(org),
18
            ))
19
            org
20
        }
21
}

No publisher port. No kafkaTemplate.send. No callback. The SDK dispatcher does the rest.

Recipe for adopting in a new service: add the codehuntersio-sdk-event-messaging starter, run the SDK’s outbox_message + shedlock migrations, set spring.application.name, inject OutboxRepositoryPort + OutboxEventFactory in use cases. To swap broker, override MessagePublisherPort with your KafkaMessagePublisherAdapter — every @ConditionalOnMissingBean in the SDK auto-config defers.

For the schema, claim SQL, ShedLock annotation, retry math, idempotency, schema evolution, tracing, metrics and pre-merge checklist, read messaging.md — do NOT reinvent these here.

Error handling strategy

• Domain/application: use domain-specific exceptions or a Result type.
• Entry points: convert exceptions to HTTP status/GraphQL errors (see GlobalExceptionHandler).
• Infrastructure: wrap low-level exceptions and propagate meaningful errors upward.

Chain of Responsibility Pattern (Decorator Pattern)

• Use Chain of Responsibility to layer cross-cutting concerns (caching, metrics, logging) in front of core adapters.
• This pattern allows adding functionality without modifying use cases or core repository implementations.

Implementation:

1. Define ChainablePort Interface (in infrastructure or application support):

   1
   interface ChainablePort<T> : Ordered {
   2
       fun setDelegate(delegate: T)
   3
   }

   Java:

   1
   public interface ChainablePort<T> extends Ordered {
   2
       void setDelegate(T delegate);
   3
   }

2. Implement Decorators with @Order:

   1
   // Cache layer - highest priority (checked first)
   2
   @Component
   3
   @Order(50)
   4
   class OrganizationCacheAdapter(
   5
       private val redisTemplate: RedisTemplate<String, Any>
   6
   ) : OrganizationRepositoryPort, ChainablePort<OrganizationRepositoryPort> {
   7
   
   8
       private lateinit var delegate: OrganizationRepositoryPort
   9
   
   10
       override fun setDelegate(delegate: OrganizationRepositoryPort) {
   11
           this.delegate = delegate
   12
       }
   13
   
   14
       override fun findById(id: UUID): Organization? {
   15
           // Check cache first
   16
           val cached = redisTemplate.opsForValue().get("org:$id")
   17
           if (cached != null) {
   18
               log.debug("Cache hit for organization: {}", id)
   19
               return cached as Organization
   20
           }
   21
   
   22
           // Cache miss - delegate to next in chain (typically DB adapter)
   23
           val result = delegate.findById(id)
   24
           if (result != null) {
   25
               redisTemplate.opsForValue().set("org:$id", result, Duration.ofMinutes(10))
   26
           }
   27
           return result
   28
       }
   29
   
   30
       override fun save(organization: Organization): Organization {
   31
           val result = delegate.save(organization)
   32
           // Invalidate or update cache
   33
           redisTemplate.delete("org:${result.id}")
   34
           return result
   35
       }
   36
   }
   37
   
   38
   // Metrics layer - medium priority
   39
   @Component
   40
   @Order(75)
   41
   class OrganizationMetricsAdapter(
   42
       private val meterRegistry: MeterRegistry
   43
   ) : OrganizationRepositoryPort, ChainablePort<OrganizationRepositoryPort> {
   44
   
   45
       private lateinit var delegate: OrganizationRepositoryPort
   46
   
   47
       override fun setDelegate(delegate: OrganizationRepositoryPort) {
   48
           this.delegate = delegate
   49
       }
   50
   
   51
       override fun findById(id: UUID): Organization? {
   52
           val timer = Timer.start(meterRegistry)
   53
           return try {
   54
               val result = delegate.findById(id)
   55
               meterRegistry.counter("repository.findById.success",
   56
                   Tags.of("entity", "organization")).increment()
   57
               result
   58
           } catch (ex: Exception) {
   59
               meterRegistry.counter("repository.findById.error",
   60
                   Tags.of("entity", "organization")).increment()
   61
               throw ex
   62
           } finally {
   63
               timer.stop(meterRegistry.timer("repository.findById.duration",
   64
                   Tags.of("entity", "organization")))
   65
           }
   66
       }
   67
   }
   68
   
   69
   // Database adapter - lowest priority (fallback/actual implementation)
   70
   @Component
   71
   @Order(100)
   72
   class OrganizationRepositoryAdapter(
   73
       private val jdbcRepository: OrganizationJdbcRepository,
   74
       private val mapper: EntityJdbcMapper
   75
   ) : OrganizationRepositoryPort {
   76
   
   77
       override fun findById(id: UUID): Organization? {
   78
           return jdbcRepository.findById(id)
   79
               .map { mapper.toDomain(it) }
   80
               .orElse(null)
   81
       }
   82
   
   83
       override fun save(organization: Organization): Organization {
   84
           val entity = mapper.toEntityForInsert(organization)
   85
           return mapper.toDomain(jdbcRepository.save(entity))
   86
       }
   87
   }

   Java:

   1
   // Cache layer - highest priority (checked first)
   2
   @Component
   3
   @Order(50)
   4
   public class OrganizationCacheAdapter implements OrganizationRepositoryPort, ChainablePort<OrganizationRepositoryPort> {
   5
   
   6
       private final RedisTemplate<String, Object> redisTemplate;
   7
       private OrganizationRepositoryPort delegate;
   8
   
   9
       public OrganizationCacheAdapter(RedisTemplate<String, Object> redisTemplate) {
   10
           this.redisTemplate = redisTemplate;
   11
       }
   12
   
   13
       @Override
   14
       public void setDelegate(OrganizationRepositoryPort delegate) {
   15
           this.delegate = delegate;
   16
       }
   17
   
   18
       @Override
   19
       public Organization findById(UUID id) {
   20
           // Check cache first
   21
           Object cached = redisTemplate.opsForValue().get("org:" + id);
   22
           if (cached != null) {
   23
               log.debug("Cache hit for organization: {}", id);
   24
               return (Organization) cached;
   25
           }
   26
   
   27
           // Cache miss - delegate to next in chain (typically DB adapter)
   28
           Organization result = delegate.findById(id);
   29
           if (result != null) {
   30
               redisTemplate.opsForValue().set("org:" + id, result, Duration.ofMinutes(10));
   31
           }
   32
           return result;
   33
       }
   34
   
   35
       @Override
   36
       public Organization save(Organization organization) {
   37
           Organization result = delegate.save(organization);
   38
           // Invalidate or update cache
   39
           redisTemplate.delete("org:" + result.getId());
   40
           return result;
   41
       }
   42
   
   43
       @Override
   44
       public int getOrder() { return 50; }
   45
   }
   46
   
   47
   // Metrics layer - medium priority
   48
   @Component
   49
   @Order(75)
   50
   public class OrganizationMetricsAdapter implements OrganizationRepositoryPort, ChainablePort<OrganizationRepositoryPort> {
   51
   
   52
       private final MeterRegistry meterRegistry;
   53
       private OrganizationRepositoryPort delegate;
   54
   
   55
       public OrganizationMetricsAdapter(MeterRegistry meterRegistry) {
   56
           this.meterRegistry = meterRegistry;
   57
       }
   58
   
   59
       @Override
   60
       public void setDelegate(OrganizationRepositoryPort delegate) {
   61
           this.delegate = delegate;
   62
       }
   63
   
   64
       @Override
   65
       public Organization findById(UUID id) {
   66
           Timer.Sample timer = Timer.start(meterRegistry);
   67
           try {
   68
               Organization result = delegate.findById(id);
   69
               meterRegistry.counter("repository.findById.success",
   70
                   Tags.of("entity", "organization")).increment();
   71
               return result;
   72
           } catch (Exception ex) {
   73
               meterRegistry.counter("repository.findById.error",
   74
                   Tags.of("entity", "organization")).increment();
   75
               throw ex;
   76
           } finally {
   77
               timer.stop(meterRegistry.timer("repository.findById.duration",
   78
                   Tags.of("entity", "organization")));
   79
           }
   80
       }
   81
   
   82
       @Override
   83
       public int getOrder() { return 75; }
   84
   }
   85
   
   86
   // Database adapter - lowest priority (fallback/actual implementation)
   87
   @Component
   88
   @Order(100)
   89
   public class OrganizationRepositoryAdapter implements OrganizationRepositoryPort {
   90
   
   91
       private final OrganizationJdbcRepository jdbcRepository;
   92
       private final EntityJdbcMapper mapper;
   93
   
   94
       public OrganizationRepositoryAdapter(OrganizationJdbcRepository jdbcRepository, EntityJdbcMapper mapper) {
   95
           this.jdbcRepository = jdbcRepository;
   96
           this.mapper = mapper;
   97
       }
   98
   
   99
       @Override
   100
       public Organization findById(UUID id) {
   101
           return jdbcRepository.findById(id)
   102
               .map(mapper::toDomain)
   103
               .orElse(null);
   104
       }
   105
   
   106
       @Override
   107
       public Organization save(Organization organization) {
   108
           var entity = mapper.toEntityForInsert(organization);
   109
           return mapper.toDomain(jdbcRepository.save(entity));
   110
       }
   111
   }

3. Wire Chain in Configuration (bootstrap module):

   1
   @Configuration
   2
   class UseCaseConfig(
   3
       private val factory: BeanFactory
   4
   ) {
   5
   
   6
       @Bean
   7
       @Primary
   8
       fun organizationRepository(): OrganizationRepositoryPort {
   9
           return buildChain(OrganizationRepositoryPort::class.java)
   10
       }
   11
   
   12
       private fun <T : Any> buildChain(type: Class<T>): T {
   13
           // Get all beans of this type
   14
           val beans = factory.getBeansOfType(type).values.toList()
   15
   
   16
           // Sort by order (lowest number = highest priority)
   17
           val ordered = beans.sortedWith(OrderComparator.INSTANCE)
   18
   
   19
           // Wire delegates: each adapter delegates to the next
   20
           for (i in 0 until ordered.size - 1) {
   21
               val current = ordered[i]
   22
               val next = ordered[i + 1]
   23
               if (current is ChainablePort<*>) {
   24
                   @Suppress("UNCHECKED_CAST")
   25
                   (current as ChainablePort<T>).setDelegate(next)
   26
               }
   27
           }
   28
   
   29
           // Return the first (highest priority) adapter
   30
           return ordered.first()
   31
       }
   32
   }

Key Benefits:

• Separation of Concerns: Cross-cutting concerns isolated from business logic
• Open/Closed Principle: Add new decorators without modifying existing code
• Composability: Mix and match decorators as needed
• Testability: Test each layer independently; mock decorators in use case tests
• Runtime Configuration: Enable/disable decorators via Spring profiles or feature flags

Usage in Use Cases:

1
class CreateOrganizationUseCase(
2
    private val organizationRepository: OrganizationRepositoryPort // Receives the chain head
3
) : CreateOrganizationPort {
4
    override fun execute(command: CreateOrganizationCommand): Organization {
5
        // Use case doesn't know about caching or metrics - just calls the repository
6
        return organizationRepository.save(command.toOrganization())
7
    }
8
}

Order Guidelines:

• 1-49: Pre-processing decorators (validation, transformation)
• 50-74: Caching layers
• 75-89: Metrics and observability
• 90-99: Logging and auditing
• 100+: Actual implementations (database, external APIs)

Testing strategy

• Unit tests in domain and application modules.
• Adapters: slice/integration tests (e.g., using Testcontainers with a real DB/Kafka when needed).
• Contract tests for REST/GraphQL schemas to prevent breaking changes.
• Architecture tests with ArchUnit: Enforce hexagonal architecture boundaries at build time.

Architecture Testing with ArchUnit:

Create tests to enforce architectural rules:

1
@AnalyzeClasses(packages = ["com.example.platform"])
2
class HexagonalArchitectureTest {
3

4
    @ArchTest
5
    val domainShouldNotDependOnInfrastructure = noClasses()
6
        .that().resideInAPackage("..domain..")
7
        .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
8
        .because("Domain must be free from infrastructure dependencies")
9

10
    @ArchTest
11
    val domainShouldNotDependOnApplication = noClasses()
12
        .that().resideInAPackage("..domain..")
13
        .should().dependOnClassesThat().resideInAPackage("..usecase..")
14
        .because("Domain must not depend on application layer")
15

16
    @ArchTest
17
    val applicationUseCasesShouldNotDependOnInfrastructure = noClasses()
18
        .that().resideInAPackage("..usecase..")
19
        .and().haveSimpleNameEndingWith("UseCase")
20
        .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
21
        .because("Use cases must not depend on infrastructure implementations")
22

23
    @ArchTest
24
    val entryPointsShouldNotDependOnDrivenAdapters = noClasses()
25
        .that().resideInAPackage("..infrastructure.entry.points..")
26
        .should().dependOnClassesThat().resideInAPackage("..infrastructure.driven.adapters..")
27
        .because("Entry points should only depend on ports, not on driven adapter implementations")
28

29
    @ArchTest
30
    val drivenAdaptersShouldNotAccessUseCases = noClasses()
31
        .that().resideInAPackage("..infrastructure.driven.adapters..")
32
        .should().accessClassesThat().resideInAPackage("..usecase..")
33
        .because("Driven adapters should not directly access use case implementations")
34

35
    @ArchTest
36
    val portsShouldBeInterfaces = classes()
37
        .that().resideInAPackage("..port..")
38
        .should().beInterfaces()
39
        .because("Ports should be contracts (interfaces)")
40

41
    @ArchTest
42
    val useCasesShouldNotHaveSpringAnnotations = noClasses()
43
        .that().resideInAPackage("..usecase..")
44
        .should().beAnnotatedWith("org.springframework.stereotype.Service")
45
        .orShould().beAnnotatedWith("org.springframework.transaction.annotation.Transactional")
46
        .because("Use cases should be framework-agnostic")
47

48
    @ArchTest
49
    val domainShouldNotHaveSpringAnnotations = noClasses()
50
        .that().resideInAPackage("..domain..")
51
        .should().dependOnClassesThat().resideInAPackage("org.springframework..")
52
        .because("Domain must be pure and framework-free")
53

54
    // Outbox-first: use cases NEVER touch broker SDKs or the publisher port.
55
    @ArchTest
56
    val useCasesShouldNotUseBrokerSdks = noClasses()
57
        .that().resideInAPackage("..usecase..")
58
        .should().dependOnClassesThat().resideInAnyPackage(
59
            "org.springframework.kafka..",
60
            "org.apache.kafka..",
61
            "org.springframework.amqp..",
62
            "com.rabbitmq..",
63
            "software.amazon.awssdk.services.sqs..",
64
            "software.amazon.awssdk.services.sns..",
65
        )
66
        .because("Use cases must publish via the outbox; broker SDKs belong in the dispatcher adapter")
67

68
    @ArchTest
69
    val useCasesShouldNotInjectMessagePublisherPort = noClasses()
70
        .that().resideInAPackage("..usecase..")
71
        .should().dependOnClassesThat().haveSimpleName("MessagePublisherPort")
72
        .because("MessagePublisherPort is the dispatcher's port; use cases inject OutboxRepositoryPort + OutboxEventFactory")
73

74
    @ArchTest
75
    val useCasesShouldNotInjectDomainPublisherPorts = noClasses()
76
        .that().resideInAPackage("..usecase..")
77
        .should().dependOnClassesThat().haveSimpleNameEndingWith("PublisherPort")
78
        .because("No domain-specific publisher ports (XxxPublisherPort) — they invite dual-write; use OutboxRepositoryPort instead")
79

80
    @ArchTest
81
    val brokerTemplatesShouldOnlyLiveInPublisherAdapters = noClasses()
82
        .that().dependOnClassesThat().haveSimpleNameEndingWith("KafkaTemplate")
83
        .or().dependOnClassesThat().haveSimpleNameEndingWith("RabbitTemplate")
84
        .should().resideOutsideOfPackages(
85
            "..infrastructure.driven.adapters.kafka..",
86
            "..infrastructure.driven.adapters.rabbitmq..",
87
            "..infrastructure.entry.points.scheduler..",   // SDK OutboxScheduler exception
88
        )
89
        .because("Broker templates may only be wired into MessagePublisherPort adapters")
90
}

Java:

1
@AnalyzeClasses(packages = "com.example.platform")
2
class HexagonalArchitectureTest {
3

4
    @ArchTest
5
    static final ArchRule domainShouldNotDependOnInfrastructure = noClasses()
6
        .that().resideInAPackage("..domain..")
7
        .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
8
        .because("Domain must be free from infrastructure dependencies");
9

10
    @ArchTest
11
    static final ArchRule domainShouldNotDependOnApplication = noClasses()
12
        .that().resideInAPackage("..domain..")
13
        .should().dependOnClassesThat().resideInAPackage("..usecase..")
14
        .because("Domain must not depend on application layer");
15

16
    @ArchTest
17
    static final ArchRule applicationUseCasesShouldNotDependOnInfrastructure = noClasses()
18
        .that().resideInAPackage("..usecase..")
19
        .and().haveSimpleNameEndingWith("UseCase")
20
        .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
21
        .because("Use cases must not depend on infrastructure implementations");
22

23
    @ArchTest
24
    static final ArchRule entryPointsShouldNotDependOnDrivenAdapters = noClasses()
25
        .that().resideInAPackage("..infrastructure.entry.points..")
26
        .should().dependOnClassesThat().resideInAPackage("..infrastructure.driven.adapters..")
27
        .because("Entry points should only depend on ports, not on driven adapter implementations");
28

29
    @ArchTest
30
    static final ArchRule drivenAdaptersShouldNotAccessUseCases = noClasses()
31
        .that().resideInAPackage("..infrastructure.driven.adapters..")
32
        .should().accessClassesThat().resideInAPackage("..usecase..")
33
        .because("Driven adapters should not directly access use case implementations");
34

35
    @ArchTest
36
    static final ArchRule portsShouldBeInterfaces = classes()
37
        .that().resideInAPackage("..port..")
38
        .should().beInterfaces()
39
        .because("Ports should be contracts (interfaces)");
40

41
    @ArchTest
42
    static final ArchRule useCasesShouldNotHaveSpringAnnotations = noClasses()
43
        .that().resideInAPackage("..usecase..")
44
        .should().beAnnotatedWith("org.springframework.stereotype.Service")
45
        .orShould().beAnnotatedWith("org.springframework.transaction.annotation.Transactional")
46
        .because("Use cases should be framework-agnostic");
47

48
    @ArchTest
49
    static final ArchRule domainShouldNotHaveSpringAnnotations = noClasses()
50
        .that().resideInAPackage("..domain..")
51
        .should().dependOnClassesThat().resideInAPackage("org.springframework..")
52
        .because("Domain must be pure and framework-free");
53

54
    // Outbox-first: use cases NEVER touch broker SDKs or the publisher port.
55
    @ArchTest
56
    static final ArchRule useCasesShouldNotUseBrokerSdks = noClasses()
57
        .that().resideInAPackage("..usecase..")
58
        .should().dependOnClassesThat().resideInAnyPackage(
59
            "org.springframework.kafka..",
60
            "org.apache.kafka..",
61
            "org.springframework.amqp..",
62
            "com.rabbitmq..",
63
            "software.amazon.awssdk.services.sqs..",
64
            "software.amazon.awssdk.services.sns..")
65
        .because("Use cases must publish via the outbox; broker SDKs belong in the dispatcher adapter");
66

67
    @ArchTest
68
    static final ArchRule useCasesShouldNotInjectMessagePublisherPort = noClasses()
69
        .that().resideInAPackage("..usecase..")
70
        .should().dependOnClassesThat().haveSimpleName("MessagePublisherPort")
71
        .because("MessagePublisherPort is the dispatcher's port; use cases inject OutboxRepositoryPort + OutboxEventFactory");
72

73
    @ArchTest
74
    static final ArchRule useCasesShouldNotInjectDomainPublisherPorts = noClasses()
75
        .that().resideInAPackage("..usecase..")
76
        .should().dependOnClassesThat().haveSimpleNameEndingWith("PublisherPort")
77
        .because("No domain-specific publisher ports (XxxPublisherPort) — they invite dual-write; use OutboxRepositoryPort instead");
78

79
    @ArchTest
80
    static final ArchRule brokerTemplatesShouldOnlyLiveInPublisherAdapters = noClasses()
81
        .that().dependOnClassesThat().haveSimpleNameEndingWith("KafkaTemplate")
82
        .or().dependOnClassesThat().haveSimpleNameEndingWith("RabbitTemplate")
83
        .should().resideOutsideOfPackages(
84
            "..infrastructure.driven.adapters.kafka..",
85
            "..infrastructure.driven.adapters.rabbitmq..",
86
            "..infrastructure.entry.points.scheduler..")
87
        .because("Broker templates may only be wired into MessagePublisherPort adapters");
88
}

Run these tests as part of your build:

1
// In build.gradle.kts (bootstrap module)
2
dependencies {
3
    testImplementation("com.tngtech.archunit:archunit-junit5:1.3.0")
4
}
5

6
tasks.test {
7
    useJUnitPlatform()
8
}

Benefits:

• Fail Fast: Architecture violations caught at compile/test time, not code review
• Documentation: Tests serve as executable architecture documentation
• Regression Prevention: Prevents accidental dependency direction reversals
• Onboarding: New developers understand boundaries from reading tests

Observability & Metrics Adapters:

Use decorators to add metrics without polluting business logic:

1
@Component
2
@Order(75)
3
class OrganizationMetricsAdapter(
4
    private val meterRegistry: MeterRegistry
5
) : OrganizationRepositoryPort, ChainablePort<OrganizationRepositoryPort> {
6

7
    private lateinit var delegate: OrganizationRepositoryPort
8

9
    override fun setDelegate(delegate: OrganizationRepositoryPort) {
10
        this.delegate = delegate
11
    }
12

13
    private fun <T> record(operation: String, block: () -> T): T {
14
        val tags = Tags.of("entity", "organization", "operation", operation)
15
        val timer = Timer.start(meterRegistry)
16

17
        return try {
18
            val result = block()
19
            meterRegistry.counter("repository.calls", tags.and("success", "true")).increment()
20
            result
21
        } catch (ex: Exception) {
22
            meterRegistry.counter("repository.calls", tags.and("success", "false")).increment()
23
            meterRegistry.counter("repository.errors", tags.and("error", ex.javaClass.simpleName)).increment()
24
            throw ex
25
        } finally {
26
            timer.stop(meterRegistry.timer("repository.duration", tags))
27
        }
28
    }
29

30
    override fun findById(id: UUID): Organization? {
31
        return record("findById") { delegate.findById(id) }
32
    }
33

34
    override fun save(organization: Organization): Organization {
35
        return record("save") { delegate.save(organization) }
36
    }
37

38
    override fun update(organization: Organization): Organization {
39
        return record("update") { delegate.update(organization) }
40
    }
41

42
    override fun getOrder(): Int = 75
43
}

Java:

1
@Component
2
@Order(75)
3
public class OrganizationMetricsAdapter implements OrganizationRepositoryPort, ChainablePort<OrganizationRepositoryPort> {
4

5
    private final MeterRegistry meterRegistry;
6
    private OrganizationRepositoryPort delegate;
7

8
    public OrganizationMetricsAdapter(MeterRegistry meterRegistry) {
9
        this.meterRegistry = meterRegistry;
10
    }
11

12
    @Override
13
    public void setDelegate(OrganizationRepositoryPort delegate) {
14
        this.delegate = delegate;
15
    }
16

17
    private <T> T record(String operation, Supplier<T> block) {
18
        Tags tags = Tags.of("entity", "organization", "operation", operation);
19
        Timer.Sample timer = Timer.start(meterRegistry);
20

21
        try {
22
            T result = block.get();
23
            meterRegistry.counter("repository.calls", tags.and("success", "true")).increment();
24
            return result;
25
        } catch (Exception ex) {
26
            meterRegistry.counter("repository.calls", tags.and("success", "false")).increment();
27
            meterRegistry.counter("repository.errors", tags.and("error", ex.getClass().getSimpleName())).increment();
28
            throw ex;
29
        } finally {
30
            timer.stop(meterRegistry.timer("repository.duration", tags));
31
        }
32
    }
33

34
    @Override
35
    public Organization findById(UUID id) {
36
        return record("findById", () -> delegate.findById(id));
37
    }
38

39
    @Override
40
    public Organization save(Organization organization) {
41
        return record("save", () -> delegate.save(organization));
42
    }
43

44
    @Override
45
    public Organization update(Organization organization) {
46
        return record("update", () -> delegate.update(organization));
47
    }
48

49
    @Override
50
    public int getOrder() { return 75; }
51
}

Available Metrics:

• repository.calls{entity,operation,success} - Counter for all repository operations
• repository.duration{entity,operation} - Timer for operation duration
• repository.errors{entity,operation,error} - Counter for errors by type

Export to Prometheus/Grafana via Spring Boot Actuator:

1
management:
2
  endpoints:
3
    web:
4
      exposure:
5
        include: health,info,metrics,prometheus
6
  metrics:
7
    export:
8
      prometheus:
9
        enabled: true

Versioning & changes

• Backward compatibility for APIs and messages. Use additive DB migrations.

Checklist before adding new features

• Define/extend inbound and outbound ports as needed in application.
• Implement adapters in the correct infrastructure module.
• Add mappers and DTOs; ensure no domain leakage.
• Add Liquibase changeSets and MyBatis mappings where applicable.
• Write tests at the appropriate layers.
• Wire beans in bootstrap config if auto-detection isn’t sufficient.