---

name: laravel-architecture description: Design Laravel app architecture with services, repositories, actions, and clean code patterns. Use when structuring projects, creating services, implementing DI, or organizing code layers. user-invocable: false

Laravel Architecture Patterns

Documentation

Core

• installation.md - Installation and setup
• configuration.md - Configuration
• structure.md - Directory structure
• lifecycle.md - Request lifecycle
• upgrade.md - Upgrade guide
• releases.md - Release notes

Service Container & Providers

• container.md - Service container
• providers.md - Service providers
• facades.md - Facades
• contracts.md - Contracts
• context.md - Context

CLI & Tools

• artisan.md - Artisan CLI
• packages.md - Package development
• helpers.md - Helper functions

Development Environment

• sail.md - Docker development
• valet.md - macOS development
• homestead.md - Vagrant development

Performance & Deployment

• octane.md - High performance server
• envoy.md - Deployment tasks
• deployment.md - Deployment guide

Advanced

• processes.md - Process management
• concurrency.md - Concurrency
• filesystem.md - File storage
• pennant.md - Feature flags
• mcp.md - Model Context Protocol

Error Handling

• errors.md - Error handling
• logging.md - Logging

Recommended Structure

Copyapp/
├── Actions/              # Single-purpose action classes
├── Services/             # Business logic
├── Repositories/         # Data access layer
│   └── Contracts/
├── Http/
│   ├── Controllers/      # Thin controllers
│   ├── Requests/         # Form validation
│   └── Resources/        # API transformations
├── Models/               # Eloquent models only
├── Enums/                # PHP 8.1+ enums
├── Events/               # Domain events
├── Listeners/            # Event handlers
└── Policies/             # Authorization

Service Pattern

Copy<?php

declare(strict_types=1);

namespace App\Services;

final readonly class UserService
{
    public function __construct(
        private UserRepositoryInterface $repository,
    ) {}

    public function create(CreateUserDTO $dto): User
    {
        return $this->repository->create($dto->toArray());
    }
}

Dependency Injection

Copy// AppServiceProvider.php
public function register(): void
{
    $this->app->bind(
        UserRepositoryInterface::class,
        UserRepository::class
    );
}