ArchPilotExecutable architecture guardrails

Search docs

Docs search

Validation rule

Back to Rule Catalog
AP-TXN-001Transaction Boundaries

Transaction boundary too broad

Flags transactions that appear to wrap more work than necessary.

warningviolationNo auto-fix

How to fix

  1. Narrow the transaction to the required write set.
  2. Move reads and non-database work outside the transaction.
  3. Split independent workflows into separate transaction scopes.

What the rule validates

A transaction scope includes broad orchestration or unrelated work.

Why it matters

Oversized transactions increase lock duration, retry complexity, and failure blast radius.

Common causes

  • A transaction wraps an entire service method.
  • Read-only work sits inside a write transaction.
  • Several independent workflows were grouped together.

Typical violation example

A checkout transaction wraps pricing lookup, email rendering, external API calls, and writes.

Typical compliant example

The transaction wraps only the related database writes that must commit together.

Related rules

AP-TXN-002 - Transaction started in controller/API layerAP-TXN-003 - Nested transaction riskAP-TXN-004 - Long-running workflow inside transaction

Adjacent categories

Transaction BoundariesApplication Layering

Related files/config

  • apps/api/src
  • apps/web
  • packages

Related CLI commands

  • archpilot validate
  • archpilot validate --ci

Related docs

Rule CatalogTransaction BoundariesApplication Layering
AP-TXN-001 - Transaction boundary too broad | ArchPilot Docs