ArchPilotExecutable architecture guardrails

Search docs

Docs search

Validation rule

Back to Rule Catalog
AP-TXN-002Transaction Boundaries

Transaction started in controller/API layer

Flags transactions initiated from transport-layer code.

warningviolationNo auto-fix

How to fix

  1. Move transaction orchestration into the application service.
  2. Keep controllers focused on request/response handling.
  3. Test transaction behavior at the service boundary.

What the rule validates

A controller or API route appears to own transaction orchestration.

Why it matters

Transaction policy belongs near application workflows, not HTTP transport concerns.

Common causes

  • A controller directly uses the ORM transaction API.
  • A route handler grew into an orchestration method.
  • Service boundaries were skipped for a mutation.

Typical violation example

POST /billing/checkout starts prisma.$transaction in the controller method.

Typical compliant example

The controller calls BillingService.createCheckoutSession(...), which owns the transaction.

Related rules

AP-TXN-001 - Transaction boundary too broadAP-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-002 - Transaction started in controller/API layer | ArchPilot Docs