ArchPilotExecutable architecture guardrails

Search docs

Docs search

Validation rule

Back to Rule Catalog
AP-APP-004Application Layering

Package responsibility mismatch

Flags files whose responsibilities do not match the package or module they live in.

warningviolationNo auto-fix

How to fix

  1. Move the file to the package that owns the responsibility.
  2. Split shared helpers into a clearer lower-level package.
  3. Update imports and module contracts after the move.

What it means

A package appears to contain code for a different architectural responsibility.

Why it matters

Responsibility drift makes ownership unclear and causes modules to become accidental catch-alls.

Common causes

  • Shared helpers were placed in the nearest package.
  • A feature moved but supporting code stayed behind.
  • The package boundary is too broad.

Example bad pattern

A payments package contains user-invitation email workflow code.

Example good pattern

Invitation workflow code lives in the platform or identity package that owns it.

Related files/config

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

Related CLI commands

  • archpilot validate
  • archpilot validate --ci

Related docs

Rule CatalogApplication LayeringDependency Rules & Module Contracts
AP-APP-004 - Package responsibility mismatch | ArchPilot Docs