{
    "slug": "clean_architecture",
    "term": "Clean Architecture",
    "category": "architecture",
    "difficulty": "advanced",
    "short": "Robert C. Martin's layered architecture that places business rules at the centre, independent of frameworks, UI, and databases.",
    "long": "Clean Architecture (Robert C. Martin) defines concentric layers: at the centre, Entities (business rules); then Use Cases (application logic); then Interface Adapters (controllers, presenters, gateways); then Frameworks and Drivers (web, DB, UI). The Dependency Rule states that dependencies must point inward — outer layers depend on inner layers, never the reverse. The domain and use case logic knows nothing about HTTP, databases, or frameworks. This makes the core testable without any infrastructure and enables replacing frameworks or databases without touching business logic.",
    "aliases": [
        "Uncle Bob clean architecture",
        "onion architecture",
        "layered clean arch"
    ],
    "tags": [
        "architecture",
        "design-pattern",
        "solid",
        "testing"
    ],
    "misconception": "Clean architecture requires a specific folder structure. Clean architecture is about dependency direction — inner layers (entities, use cases) know nothing about outer layers (frameworks, databases). The folder structure is an implementation detail; the dependency rule is the substance.",
    "why_it_matters": "Clean Architecture enforces dependency direction — inner layers (domain, use cases) know nothing about outer layers (HTTP, databases) — making the core logic testable without any infrastructure.",
    "common_mistakes": [
        "Domain entities that extend Eloquent models — the domain is now coupled to the ORM.",
        "Use case classes that import HTTP request objects — business logic should not know the delivery mechanism.",
        "Skipping the application layer and calling repositories directly from controllers.",
        "Applying Clean Architecture to simple CRUD apps — the overhead is rarely justified without complex domain logic."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "domain_driven_design",
        "separation_of_concerns",
        "dependency_injection"
    ],
    "prerequisites": [
        "hexagonal_architecture",
        "dependency_inversion",
        "solid"
    ],
    "refs": [
        "https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html"
    ],
    "bad_code": "// Domain entity coupled to Eloquent — violates dependency rule:\nclass Order extends Model { // Depends on ORM — infrastructure leaks into domain\n    protected $fillable = ['user_id', 'total', 'status'];\n    public function isPaid(): bool { return $this->status === 'paid'; }\n}",
    "good_code": "// Dependency rule: outer layers depend on inner layers, never the reverse\n\n// 1. Entity (innermost — pure PHP, zero deps)\nclass Order { public function place(Cart $cart): void { ... } }\n\n// 2. Use Case\nclass PlaceOrderUseCase {\n    public function __construct(private OrderRepository $repo) {}\n    public function execute(PlaceOrderRequest $req): OrderResponse { ... }\n}\n\n// 3. Interface Adapter (controller, presenter)\nclass OrderController {\n    public function store(Request $req): JsonResponse {\n        $response = $this->useCase->execute(PlaceOrderRequest::fromHttp($req));\n        return response()->json($response->toArray());\n    }\n}\n\n// 4. Framework/DB (outermost) — implements interfaces from inner layers\nclass EloquentOrderRepository implements OrderRepository { ... }",
    "quick_fix": "Enforce the dependency rule: source code dependencies must point inward — outer layers (frameworks, DB) depend on inner layers (use cases, entities), never the reverse",
    "severity": "info",
    "effort": "high",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/clean_architecture",
        "html_url": "https://codeclaritylab.com/glossary/clean_architecture",
        "json_url": "https://codeclaritylab.com/glossary/clean_architecture.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Clean Architecture](https://codeclaritylab.com/glossary/clean_architecture) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/clean_architecture"
            }
        }
    }
}