architecture

Apply Laravel-native architecture decisions without forcing unnecessary repositories, interfaces, DTOs, or custom layers.

SKILL.md

GitHub

Architecture

Use Laravel conventions before adding custom architecture. A good default request path is:

Route -> Controller -> Form Request -> Action/Service -> Eloquent/Integration -> Response

Do not force every layer into every feature. Add a boundary only when it makes behavior easier to test, reuse, reason about, or change.

For multi-menu dashboards, admin systems, or copied prototype apps, also use module-per-menu: default to one menu or page per module, small controllers, per-page views, shared layouts/components, and DB-backed dynamic data.

Layer Decisions

Use a controller for HTTP orchestration:

  • receive the request;
  • delegate validation and authorization;
  • call the application workflow;
  • return redirect, response, resource, view, or stream.

Use a Form Request when validation or authorization is complex, reused, or important enough to test independently.

Use an Action when a single use case needs a named command-style object.

Use a Service when a workflow coordinates multiple models, integrations, files, jobs, events, generated documents, or transactional writes.

Use a Policy or Gate for authorization rules. Keep authorization close to the boundary, but do not bury model-state rules in routes.

Avoid Overengineering

Do not add repositories, interfaces, DTOs, feature folders, or value objects by default.

Duplication alone is not sufficient reason to create a service, action, or class. Prefer local reuse or a small extraction when behavior, lifecycle, dependencies, and change surface remain simple. Create a dedicated service, action, or boundary only when there is a justified business boundary, reusable operation, dependency boundary, or meaningful complexity.

Add an interface when:

  • there are multiple implementations;
  • a provider may be swapped;
  • the domain should not depend on a concrete integration;
  • a stable contract is shared across modules;
  • a test boundary is meaningful and not just mocking for its own sake.

Add a repository only when query/data-access complexity is real or storage implementation may vary. Plain Eloquent in an Action or Service is fine for normal CRUD.

Version And Stack Detection

Before applying version-specific patterns, check:

  • Laravel version in composer.json or php artisan --version;
  • PHP version and supported syntax;
  • installed testing framework;
  • queue driver and Horizon presence;
  • Blade, Livewire, Inertia, React, Vue, Tailwind, or Vite usage;
  • Sail/container workflow versus host commands.

Implementation Checklist

  • Keep the public behavior small and testable.
  • Prefer Laravel-native APIs over custom plumbing.
  • Keep project-specific business names out of shared standards.
  • Write focused tests around the behavior being changed.
  • Run available quality checks before handoff.

Context Efficiency

Layer: 3 (Implementation)

Load this skill only when architecture decisions are needed. Do not load with unrelated skills. Keep the implementation checklist minimal: public behavior, Laravel-native APIs, focused tests, quality checks.