Transaction Boundaries

Review implemented validation rules for broad, nested, misplaced, or long-running transaction scopes.

Why it matters

Transaction Boundary findings help teams keep database transactions short, explicit, and owned by application workflows.

Overview

Review implemented validation rules for broad, nested, misplaced, or long-running transaction scopes.

Transaction Boundary findings help teams keep database transactions short, explicit, and owned by application workflows.

Why it matters

Cloud uses this guidance to help teams interpret local validation findings in organization context without turning the docs into implementation notes.

When this domain drifts, findings become harder to triage, ownership becomes less clear, and architecture review depends too much on individual memory.

Good architectural practices

Transactions owned by services instead of transport handlers.
Short database-focused transaction scopes.
Clear handling for nested writes and post-commit side effects.

Common anti-patterns

Transaction boundary too broad
Transaction started in controller/API layer
Nested transaction risk
Long-running workflow inside transaction

Relationship to other architecture areas

This domain usually overlaps with neighboring validation categories. Use the related pages below to understand the adjacent architecture concerns before changing policy, suppressing a finding, or accepting risk.

Implemented rules

These are the currently implemented rules in this category. Use this table for category-level orientation, then open the Rule Catalog when you need rule-specific examples and remediation guidance.

Rule ID	Rule title	Category	Severity	Short explanation	Example violation	Remediation guidance	Rule detail
AP-TXN-001	Transaction boundary too broad	Transaction Boundaries	warning	Flags transactions that appear to wrap more work than necessary.	A checkout transaction wraps pricing lookup, email rendering, external API calls, and writes.	Narrow the transaction to the required write set. Move reads and non-database work outside the transaction. Split independent workflows into separate transaction scopes.	View rule page
AP-TXN-002	Transaction started in controller/API layer	Transaction Boundaries	warning	Flags transactions initiated from transport-layer code.	POST /billing/checkout starts prisma.$transaction in the controller method.	Move transaction orchestration into the application service. Keep controllers focused on request/response handling. Test transaction behavior at the service boundary.	View rule page
AP-TXN-003	Nested transaction risk	Transaction Boundaries	warning	Flags workflows where transactions may be nested or composed unsafely.	inviteUsersInTransaction(...) calls createMembership(...), which starts another transaction.	Pass a transaction client/context through nested work. Ensure only the top-level workflow opens the transaction. Document transaction ownership in service APIs.	View rule page
AP-TXN-004	Long-running workflow inside transaction	Transaction Boundaries	warning	Flags transactions that include slow external or asynchronous work.	A transaction writes invitation rows and sends every invitation email before commit.	Commit database changes before external side effects. Use an outbox or job queue for post-commit work. Keep transaction scopes short and database-focused.	View rule page

Application Layering Event Architecture Rule Catalog

Next steps

Domain Model Quality API Design