architecture

Scope

• Apply these rules only if the project uses pekral/arch-app-services.
• This rule extends core Laravel conventions with package-specific architectural constraints.
• Follow pekral/arch-app-services as the source of truth, including package examples and conventions.

Architecture

• All business logic must follow the Action pattern.
• Mandatory orchestration flow:
  • Controller / Job / Command / Listener / Livewire Component -> Action -> ModelService -> Repository (read) / ModelManager (write)
• Entry points must stay thin:
  • accept input
  • validate input or delegate validation
  • call an Action
  • return a response or update UI state
• Only Laravel-native class types exist in the application; every other concern is a pekral/arch-app-services layer. The only non-business-logic classes allowed are the framework's own building blocks — controllers, jobs, console commands, listeners, events, Livewire components, middleware, FormRequests, Mailables, Notifications, policies, service providers, custom Rule classes, Enums, DTOs, Eloquent models, and framework boilerplate. All other logic must be split by responsibility into the dedicated classes defined by pekral/arch-app-services — Actions, Model Services (Pekral\Arch\Service\BaseModelService), Repositories (Pekral\Arch\Repository\Mysql\BaseRepository), ModelManagers (Pekral\Arch\ModelManager\Mysql\BaseModelManager), Data Validators (Pekral\Arch\DataValidation\DataValidator), and Data Builders (Pekral\Arch\DataBuilder\DataBuilder). Introducing an ad-hoc class that is neither a Laravel-native type nor one of these arch-app-services layers (a bare Helper, Manager, Handler, Util, Processor, Builder, Mapper, Validator, Service that does not extend BaseModelService, etc.) to host business logic is forbidden — move that logic into the correct layer above. An application-owned Facade is never one of those homes — the service layer caps at BaseModelService, see Model Services → No application Facades.
• Actions return plain domain data, never HTTP responses. An Action's __invoke() returns a domain value (a Model, a DTO, a Collection, a scalar, void) — never an Illuminate\Http\Response / JsonResponse / RedirectResponse, and never the result of response(), response()->json(), redirect(), back(), view(), or any other HTTP-response builder. Translating domain data into an HTTP response (status code, headers, JSON envelope, redirect) is always the controller's job — the controller is the single owner of client↔server communication. Jobs, commands, and listeners likewise consume the Action's domain return value directly.