laravel

Architecture

• Keep business logic out of controllers, middleware, and Blade views.
• Simple, self-contained domain logic (predicates on the model's own attributes, computed values derived from already-loaded data, simple state derivations that touch nothing else) may live as methods on the Eloquent model itself — see the Database and Eloquent section for the boundary. Anything that needs external services, repositories, model managers, or new database queries goes through an Action.
• Use Actions for orchestration-heavy use cases.
• Treat controllers, jobs, events, listeners, and commands as entry points.
• Entry points must stay slim: validate input, delegate work, return a response.

Layer Responsibilities

• Controllers: accept validated input, authorize access, delegate work.
• Actions: orchestrate use cases and business flows.
• Services: focused stateless domain/application services.
• Repositories: read-only data access.
• ModelManagers: write-only persistence.
• Data Builders: multi-method classes that map, hydrate, or normalize input into DTOs. Not Action pattern — no __invoke(). Never query the database.
• Eloquent Models: framework boilerplate (relationships, scopes, casts, accessors) plus simple self-contained domain methods on own data — see the Database and Eloquent section for the boundary.
• Shared Concerns (app/Concerns/): globally shared and reusable logic — typically traits — that is domain-agnostic and consumed across two or more unrelated domains. Never a home for domain-specific code. See the Shared Concerns section below.

Shared Concerns

• app/Concerns/ is the canonical home for all globally shared and reusable logic in the application — typically traits, but also small reusable helpers and value objects that exist purely to be consumed across unrelated domains.
• Place a trait or helper in app/Concerns/ only when it is globally applicable (consumed across two or more unrelated domains, layers, or entry points), domain-agnostic (no knowledge of a concrete model, aggregate, feature flow, or business rule), and reusable as-is (consumers use it without further specialization). Validation rule traits are exempt from all three — the Validation section below mandates a trait here for every rule set regardless of consumer count or domain scope.
• Never put domain-specific logic in app/Concerns/ — anything tied to a concrete model, feature flow, or business rule must live in the relevant business-logic layer under app/{Domain}/. A validation rule trait named for the aggregate it validates is the sanctioned exception: a rule set is a declarative input contract, not business logic.
• Validation rule traits (see the Validation section below) are one specific worked example of this rule, not the only allowed category.