Laravel Architecture Patterns
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Analyze existing architecture
- fuse-ai-pilot:research-expert - Verify Laravel patterns via Context7
- mcp__context7__query-docs - Check service container and DI patterns
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
Laravel architecture focuses on clean separation of concerns, dependency injection, and maintainable code organization. This skill covers everything from project structure to production deployment.
When to Use
- Structuring new Laravel projects
- Implementing services, repositories, actions
- Setting up dependency injection
- Configuring development environments
- Deploying to production
Critical Rules
- Thin controllers - Delegate business logic to services
- Interfaces in app/Contracts/ - Never alongside implementations
- DI over facades - Constructor injection for testability
- Files < 100 lines - Split larger files per SOLID
- Environment separation - .env never committed
Architecture
app/
├── Actions/ # Single-purpose action classes
├── Contracts/ # Interfaces (DI)
├── DTOs/ # Data transfer objects
├── Enums/ # PHP 8.1+ enums
├── Events/ # Domain events
├── Http/
│ ├── Controllers/ # Thin controllers
│ ├── Middleware/ # Request filters
│ ├── Requests/ # Form validation
│ └── Resources/ # API transformations
├── Jobs/ # Queued jobs
├── Listeners/ # Event handlers
├── Models/ # Eloquent models only
├── Policies/ # Authorization
├── Providers/ # Service registration
├── Repositories/ # Data access layer
└── Services/ # Business logic
Reference Guide
Core Architecture
| Reference |
When to Use |
| container.md |
Dependency injection, binding, resolution |
| providers.md |
Service registration, bootstrapping |
| facades.md |
Static proxies, real-time facades |
| contracts.md |
Interfaces, loose coupling |
| structure.md |
Directory organization |
| lifecycle.md |
Request handling flow |
Configuration & Setup
| Reference |
When to Use |
| configuration.md |
Environment, config files |
| installation.md |
New project setup |
| upgrade.md |
Version upgrades, breaking changes |
| releases.md |
Release notes, versioning |
Development Environments
| Reference |
When to Use |
| sail.md |
Docker development |
| valet.md |
macOS native development |
| homestead.md |
Vagrant (legacy) |
| octane.md |
High-performance servers |
Utilities & Tools
| Reference |
When to Use |
| artisan.md |
CLI commands, custom commands |
| helpers.md |
Global helper functions |
| filesystem.md |
File storage, S3, local |
| processes.md |
Shell command execution |
| context.md |
Request-scoped data sharing |
Advanced Features
| Reference |
When to Use |
| pennant.md |
Feature flags |
| mcp.md |
Model Context Protocol |
| concurrency.md |
Parallel execution |
Operations
| Reference |
When to Use |
| deployment.md |
Production deployment |
| envoy.md |
SSH task automation |
| logging.md |
Log channels, formatting |
| errors.md |
Exception handling |
| packages.md |
Creating packages |
Templates
| Template |
Purpose |
| UserService.php.md |
Service + repository pattern |
| AppServiceProvider.php.md |
DI bindings, bootstrapping |
| ArtisanCommand.php.md |
CLI commands, signatures, I/O |
| McpServer.php.md |
MCP servers, tools, resources, prompts |
| PennantFeature.php.md |
Feature flags, A/B testing |
| Envoy.blade.php.md |
SSH deployment automation |
| sail-config.md |
Docker Sail configuration |
| octane-config.md |
FrankenPHP, Swoole, RoadRunner |
Feature Matrix
| Feature |
Reference |
Priority |
| Service Container |
container.md |
High |
| Service Providers |
providers.md |
High |
| Directory Structure |
structure.md |
High |
| Configuration |
configuration.md |
High |
| Installation |
installation.md |
High |
| Octane (Performance) |
octane.md |
High |
| Sail (Docker) |
sail.md |
High |
| Artisan CLI |
artisan.md |
Medium |
| Deployment |
deployment.md |
Medium |
| Envoy (SSH) |
envoy.md |
Medium |
| Facades |
facades.md |
Medium |
| Contracts |
contracts.md |
Medium |
| Valet (macOS) |
valet.md |
Medium |
| Upgrade Guide |
upgrade.md |
Medium |
| Logging |
logging.md |
Medium |
| Errors |
errors.md |
Medium |
| Lifecycle |
lifecycle.md |
Medium |
| Filesystem |
filesystem.md |
Medium |
| Helpers |
helpers.md |
Low |
| Pennant (Flags) |
pennant.md |
Low |
| Context |
context.md |
Low |
| Processes |
processes.md |
Low |
| Concurrency |
concurrency.md |
Low |
| MCP |
mcp.md |
Low |
| Packages |
packages.md |
Low |
| Releases |
releases.md |
Low |
| Homestead |
homestead.md |
Low |
Quick Reference
Service Injection
public function __construct(
private readonly UserServiceInterface $userService,
) {}
Service Provider Binding
public function register(): void
{
$this->app->bind(UserServiceInterface::class, UserService::class);
$this->app->singleton(CacheService::class);
}
Artisan Command
php artisan make:provider CustomServiceProvider
php artisan make:command ProcessOrders
Environment Access
$debug = env('APP_DEBUG', false);
$config = config('app.name');
1---2name: laravel-architecture-33description: Design Laravel app architecture with services, repositories, actions, and clean code patterns. Use when structuring projects, creating services, implementing DI, or organizing code layers.4metadata:5 source: https://skillmd.com/skills/fusengine/laravel-architecture-36---78# Laravel Architecture Patterns910## Agent Workflow (MANDATORY)1112Before ANY implementation, use `TeamCreate` to spawn 3 agents:13141. **fuse-ai-pilot:explore-codebase** - Analyze existing architecture152. **fuse-ai-pilot:research-expert** - Verify Laravel patterns via Context7163. **mcp__context7__query-docs** - Check service container and DI patterns1718After implementation, run **fuse-ai-pilot:sniper** for validation.1920---2122## Overview2324Laravel architecture focuses on clean separation of concerns, dependency injection, and maintainable code organization. This skill covers everything from project structure to production deployment.2526### When to Use2728- Structuring new Laravel projects29- Implementing services, repositories, actions30- Setting up dependency injection31- Configuring development environments32- Deploying to production3334---3536## Critical Rules37381. **Thin controllers** - Delegate business logic to services392. **Interfaces in app/Contracts/** - Never alongside implementations403. **DI over facades** - Constructor injection for testability414. **Files < 100 lines** - Split larger files per SOLID425. **Environment separation** - .env never committed4344---4546## Architecture4748```text49app/50├── Actions/ # Single-purpose action classes51├── Contracts/ # Interfaces (DI)52├── DTOs/ # Data transfer objects53├── Enums/ # PHP 8.1+ enums54├── Events/ # Domain events55├── Http/56│ ├── Controllers/ # Thin controllers57│ ├── Middleware/ # Request filters58│ ├── Requests/ # Form validation59│ └── Resources/ # API transformations60├── Jobs/ # Queued jobs61├── Listeners/ # Event handlers62├── Models/ # Eloquent models only63├── Policies/ # Authorization64├── Providers/ # Service registration65├── Repositories/ # Data access layer66└── Services/ # Business logic67```6869---7071## Reference Guide7273### Core Architecture7475| Reference | When to Use |76|-----------|-------------|77| [container.md](references/container.md) | Dependency injection, binding, resolution |78| [providers.md](references/providers.md) | Service registration, bootstrapping |79| [facades.md](references/facades.md) | Static proxies, real-time facades |80| [contracts.md](references/contracts.md) | Interfaces, loose coupling |81| [structure.md](references/structure.md) | Directory organization |82| [lifecycle.md](references/lifecycle.md) | Request handling flow |8384### Configuration & Setup8586| Reference | When to Use |87|-----------|-------------|88| [configuration.md](references/configuration.md) | Environment, config files |89| [installation.md](references/installation.md) | New project setup |90| [upgrade.md](references/upgrade.md) | Version upgrades, breaking changes |91| [releases.md](references/releases.md) | Release notes, versioning |9293### Development Environments9495| Reference | When to Use |96|-----------|-------------|97| [sail.md](references/sail.md) | Docker development |98| [valet.md](references/valet.md) | macOS native development |99| [homestead.md](references/homestead.md) | Vagrant (legacy) |100| [octane.md](references/octane.md) | High-performance servers |101102### Utilities & Tools103104| Reference | When to Use |105|-----------|-------------|106| [artisan.md](references/artisan.md) | CLI commands, custom commands |107| [helpers.md](references/helpers.md) | Global helper functions |108| [filesystem.md](references/filesystem.md) | File storage, S3, local |109| [processes.md](references/processes.md) | Shell command execution |110| [context.md](references/context.md) | Request-scoped data sharing |111112### Advanced Features113114| Reference | When to Use |115|-----------|-------------|116| [pennant.md](references/pennant.md) | Feature flags |117| [mcp.md](references/mcp.md) | Model Context Protocol |118| [concurrency.md](references/concurrency.md) | Parallel execution |119120### Operations121122| Reference | When to Use |123|-----------|-------------|124| [deployment.md](references/deployment.md) | Production deployment |125| [envoy.md](references/envoy.md) | SSH task automation |126| [logging.md](references/logging.md) | Log channels, formatting |127| [errors.md](references/errors.md) | Exception handling |128| [packages.md](references/packages.md) | Creating packages |129130---131132## Templates133134| Template | Purpose |135|----------|---------|136| [UserService.php.md](references/templates/UserService.php.md) | Service + repository pattern |137| [AppServiceProvider.php.md](references/templates/AppServiceProvider.php.md) | DI bindings, bootstrapping |138| [ArtisanCommand.php.md](references/templates/ArtisanCommand.php.md) | CLI commands, signatures, I/O |139| [McpServer.php.md](references/templates/McpServer.php.md) | MCP servers, tools, resources, prompts |140| [PennantFeature.php.md](references/templates/PennantFeature.php.md) | Feature flags, A/B testing |141| [Envoy.blade.php.md](references/templates/Envoy.blade.php.md) | SSH deployment automation |142| [sail-config.md](references/templates/sail-config.md) | Docker Sail configuration |143| [octane-config.md](references/templates/octane-config.md) | FrankenPHP, Swoole, RoadRunner |144145---146147## Feature Matrix148149| Feature | Reference | Priority |150|---------|-----------|----------|151| Service Container | container.md | High |152| Service Providers | providers.md | High |153| Directory Structure | structure.md | High |154| Configuration | configuration.md | High |155| Installation | installation.md | High |156| Octane (Performance) | octane.md | High |157| Sail (Docker) | sail.md | High |158| Artisan CLI | artisan.md | Medium |159| Deployment | deployment.md | Medium |160| Envoy (SSH) | envoy.md | Medium |161| Facades | facades.md | Medium |162| Contracts | contracts.md | Medium |163| Valet (macOS) | valet.md | Medium |164| Upgrade Guide | upgrade.md | Medium |165| Logging | logging.md | Medium |166| Errors | errors.md | Medium |167| Lifecycle | lifecycle.md | Medium |168| Filesystem | filesystem.md | Medium |169| Helpers | helpers.md | Low |170| Pennant (Flags) | pennant.md | Low |171| Context | context.md | Low |172| Processes | processes.md | Low |173| Concurrency | concurrency.md | Low |174| MCP | mcp.md | Low |175| Packages | packages.md | Low |176| Releases | releases.md | Low |177| Homestead | homestead.md | Low |178179---180181## Quick Reference182183### Service Injection184185```php186public function __construct(187 private readonly UserServiceInterface $userService,188) {}189```190191### Service Provider Binding192193```php194public function register(): void195{196 $this->app->bind(UserServiceInterface::class, UserService::class);197 $this->app->singleton(CacheService::class);198}199```200201### Artisan Command202203```shell204php artisan make:provider CustomServiceProvider205php artisan make:command ProcessOrders206```207208### Environment Access209210```php211$debug = env('APP_DEBUG', false);212$config = config('app.name');213```