Laravel Architecture
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.