ArchPilotExecutable architecture guardrails

Search docs

Docs search

Validation rule

Back to Rule Catalog
AP-APP-003Application Layering

Service bypasses repository layer

Flags application services that directly reach persistence APIs where a repository boundary is expected.

warningviolationNo auto-fix

How to fix

  1. Move the query into the owning repository.
  2. Expose a narrow repository method for the service workflow.
  3. Keep tenant and transaction handling consistent with adjacent repository methods.

What the rule validates

A service appears to bypass the repository/data-access abstraction for its module.

Why it matters

Bypassing repositories scatters persistence behavior and makes transaction, tenant, and query policies harder to enforce.

Common causes

  • A service imports the ORM client directly.
  • A quick query was added during feature work.
  • The repository does not yet expose the needed method.

Typical violation example

BillingService calls prisma.invoice.findMany(...) directly while billing has an InvoiceRepository.

Typical compliant example

BillingService calls invoiceRepository.findOpenInvoicesForAccount(...).

Related rules

AP-APP-001 - Controller contains business logicAP-APP-002 - Repository contains business logicAP-APP-004 - Package responsibility mismatchAP-APP-005 - Service has oversized responsibility

Adjacent categories

Application LayeringData / Query Risk

Related files/config

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

Related CLI commands

  • archpilot validate
  • archpilot validate --ci

Related docs

Rule CatalogApplication LayeringData / Query Risk
AP-APP-003 - Service bypasses repository layer | ArchPilot Docs