home / skills / hoangnguyen0403 / agent-skills-standard / clean-architecture

clean-architecture skill

safe

This skill guides Laravel Clean Architecture adoption by organizing domains, DTOs, and ports for maintainable, testable code.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill clean-architecture

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.7 KB

---
name: Laravel Clean Architecture
description: Expert patterns for DDD, DTOs, and Ports & Adapters in Laravel.
metadata:
  labels: [laravel, ddd, architecture, solid, clean-code]
  triggers:
    files: ['app/Domains/**/*.php', 'app/Providers/*.php']
    keywords: [domain, dto, repository, contract, adapter]
---

# Laravel Clean Architecture

## **Priority: P1 (HIGH)**

## Structure

```text
app/
├── Domains/            # Logic grouped by business domain
│   └── {Domain}/
│       ├── Actions/    # Single use-case logic
│       ├── DTOs/       # Immutable data structures
│       └── Contracts/  # Interfaces for decoupling
└── Providers/          # Dependency bindings
```

## Implementation Guidelines

- **Domain Grouping**: Organize code by business domain (e.g., `User`, `Order`) instead of framework types.
- **DTOs**: Use `readonly` classes to pass data between layers; avoid raw arrays.
- **Action Classes**: Wrap business logic in single-purpose classes with `handle()` or `execute()`.
- **Repository Pattern**: Abstract Eloquent queries behind interfaces for easier testing.
- **Dependency Inversion**: Bind Interfaces to implementations in `AppServiceProvider`.
- **Model Isolation**: Keep Eloquent models lean; only include relationships and casts.

## Anti-Patterns

- **Domain Leak**: **No Eloquent in Controllers**: Use DTOs/Actions to bridge layers.
- **Array Overload**: **No raw data arrays**: Use typed DTOs for structured data.
- **Service Bloat**: **No God Services**: Break down large services into granular Actions.
- **Infrastructure Coupling**: **No hard dependencies**: Depend on abstractions, not concretions.

## References

- [DDD & Repository Patterns](references/implementation.md)

Overview

This skill codifies Laravel Clean Architecture patterns for Domain-Driven Design, DTOs, and Ports & Adapters to build maintainable, testable applications. It prescribes a domain-first folder layout, immutable data transfer objects, single-purpose action classes, and interface-based bindings. The guidance reduces framework coupling and keeps Eloquent models focused on persistence concerns.

How this skill works

The skill inspects and enforces a domain-oriented structure under app/Domains plus dependency bindings in Providers. It promotes readonly DTO classes for cross-layer data, Action classes (handle/execute) for single use-cases, and repository interfaces that hide Eloquent queries behind ports. It highlights anti-patterns like using Eloquent in controllers, raw arrays for domain data, god services, and direct infrastructure coupling, then recommends concrete replacements.

When to use it

Starting a new Laravel project to maintain long-term modularity and testability
Refactoring a legacy or monolithic Laravel app into domain modules
Building APIs where clear contracts and DTOs improve stability and client integration
Implementing automated tests with easy mocking via repository interfaces
Coaching teams on consistent architecture and coding standards across services

Best practices

Group code by business domain (app/Domains/{Domain}) not by framework type
Use immutable, typed DTOs instead of raw arrays for input/output across layers
Wrap use-cases in single-purpose Action classes (handle() or execute())
Abstract persistence with repository interfaces and bind implementations in Providers
Keep Eloquent models lean: relationships, casts, and minimal domain logic
Avoid controller-level Eloquent calls; translate requests into DTOs and delegate to Actions

Example use cases

Create a User domain with DTOs, Actions, Contracts, and a bound repository implementation
Refactor Order-related controllers into Actions and DTOs to simplify tests and reduce duplication
Add a new storage adapter by implementing the repository contract and binding it in Providers without changing domain code
Write unit tests for business logic by mocking Contracts and passing DTOs into Actions
Onboard new developers quickly using the consistent domain folder layout and action-based patterns

FAQ

How do I bind interfaces to implementations?

Bind repository and other interfaces in your Providers (e.g., AppServiceProvider) using the container so domain code depends on abstractions, not concretes.

Should DTOs be classes or arrays?

Prefer readonly, typed DTO classes to enforce structure and immutability; avoid raw arrays which leak implicit contracts and make testing brittle.

Where should validation happen?

Perform transport-level validation in form requests or controllers, map validated data into DTOs, and let Actions assume well-formed DTOs for business logic.