High-level architectural guidance for Laravel applications.
Core Concepts
philosophy.md - Foundational principles:
-
Declarative code above all else
-
Strict separation of concerns
-
Type safety first
-
All core architectural principles
patterns.md - Pattern overview:
-
Actions for domain logic
-
DTOs for data transfer
-
State machines for complex state
-
Services for external integration
-
Workflows for multi-step processes
-
Value objects for domain values
decisions.md - Pattern selection:
-
When to use each pattern
-
Decision flowcharts
-
Architectural trade-offs
-
Common scenarios
structure.md - Directory structure:
-
Complete project organization
-
File placement rules
-
Namespace conventions
-
Web vs API distinction
examples.md - Reference implementations:
-
Complete working examples
-
End-to-end workflows
-
Real-world patterns
checklist.md - Implementation checklist:
-
Setup tasks
-
Feature development workflow
-
Production deployment steps
Core Principles
-
Actions contain domain logic - Business logic lives in invokable action classes
-
Never pass primitives - Always use DTOs for data transfer
-
Thin HTTP layer - Controllers only handle HTTP concerns
-
Custom query builders - Type-safe queries over scopes
-
Strict typing -
declare(strict_types=1)in every file
Quick Decision Tree
Need to...
-
Handle domain logic? → Action
-
Transfer data? → DTO
-
Validate user input? → Form Request
-
Simple state field? → Enum
-
Complex state transitions? → State Machine
-
External API? → Service with Saloon
-
Background processing? → Job (delegates to Action)
Read decision flowcharts in decisions.md for detailed guidance.