A use case can lose atomicity when each repository call starts its own transaction: a successful save may be separated from other work that later fails. A transaction boundary defines which operations succeed or fail together. In a hexagonal application, place it on the application service handler, which knows the full scope of the use case. section 6.3.4
Table 6.2 Transaction boundary placement
|
Layer
|
@Transactional?
|
Why
|
|
Handler
(@ApplicationService
)
|
Yes
|
Orchestrates the full use case; atomic unit of work
|
|
Repository interface
|
No
|
Called within the handler's transaction; no independent boundary
|
|
Repository adapter
|
No
|
Implementation detail; inherits handler's transaction
|
|
Domain service
|
No
|
Called by the handler; operates within its transaction
|
|
Input adapter (e.g. controller)
|
No
|
Outside the hexagon; not part of the business transaction
|
The handler owns the boundary; repositories, adapters, and domain services participate without defining independent use-case boundaries. section 6.3.4
Declare intent with the Architecture Kernel’s technology-agnostic @Transactional annotation, not Spring’s annotation on the handler. A custom transaction interceptor connects that intent to the runtime transaction manager and handles rollback when failure is returned as an Either value rather than thrown as an exception. section 6.3.4 section 6.6
Publishing an article
A publish handler loads the aggregate, invokes its domain behavior, persists the new state, and collects the resulting domain event within one boundary. If the use case fails, the state change rolls back; if it succeeds, the state is committed. section 6.3.5
Command handlers use @Transactional without a read-only flag. Query handlers declare @Transactional(readOnly = true), reinforcing command-query separation by rejecting writes at the database level. section 6.3.5
Event timing affects what the boundary can protect. A synchronous listener participating in the transaction can cause rollback on failure, but external side effects are not necessarily undone. After-commit listeners run only after the primary transaction succeeds. For external integration events, an output port writes to an outbox in the same transaction as the state change; a relay delivers them, and consumers must be idempotent. section 4.7.3 section 6.6
Verify transaction outcomes in focused Spring integration tests, rather than checking only for an annotation. In Spring’s default proxy mode, a call between methods of the same class bypasses the proxy, so the inner method’s annotation does not start a transaction. section 8.7

