Laravel Domain Architecture

Agent Instructions

• When creating or modifying Domain layer components (Actions, Data Objects, Models, Enums, QueryBuilders, Collections, Events) -> consult

  references/domain-building-blocks.md

• When creating or modifying Application layer components (Controllers, Requests, Resources, Queries, Jobs, API Versioning) -> consult

  references/application-layer.md

• Do not load both references at once — use only the one relevant to the current task
• Always follow the naming conventions and anti-patterns listed below

When to Use

app/

Project Structure

Domain/

app/

app/
├── Domain/                    # Business logic (the "what")
│   ├── Invoice/
│   ├── Customer/
│   ├── Payment/
│   └── Shared/
├── Http/                      # Standard Laravel HTTP layer
│   ├── Controllers/
│   │   ├── Api/
│   │   └── Web/
│   ├── Requests/
│   ├── Resources/
│   ├── Queries/
│   ├── ViewModels/
│   └── Middleware/
├── Jobs/
├── Listeners/
├── Notifications/
├── Providers/
└── Console/

Domain Folders Are Flat

app/Domain/Invoice/
├── Invoice.php                    # Model
├── InvoiceLine.php                # Model
├── InvoiceStatus.php              # Enum
├── InvoiceData.php                # DTO (only when justified)
├── CreateInvoiceAction.php        # Action
├── MarkInvoiceAsPaidAction.php    # Action
├── CancelInvoiceAction.php        # Action
├── InvoiceQueryBuilder.php        # Custom QueryBuilder
├── InvoiceLineCollection.php      # Custom Collection
├── InvoiceCreatedEvent.php        # Event
└── InvalidTransitionException.php # Exception

app/Domain/Invoice/
├── Actions/
│   ├── CreateInvoiceAction.php
│   ├── MarkInvoiceAsPaidAction.php
│   └── CancelInvoiceAction.php
├── Models/
│   ├── Invoice.php
│   └── InvoiceLine.php
├── Enums/
│   └── InvoiceStatus.php
├── Data/
│   └── InvoiceData.php
└── ...

references/domain-building-blocks.md

Application Layer

app/Http/Controllers/Api/
├── InvoiceController.php       # Fine when there are few controllers
├── CustomerController.php
└── PaymentController.php

app/Http/Controllers/Api/
├── Invoice/
│   ├── InvoiceController.php
│   └── InvoiceStatusController.php
├── Customer/
│   └── CustomerController.php
└── Payment/
    └── PaymentController.php

API Versioning

app/Http/Controllers/Api/InvoiceController.php    # Single version — no prefix

app/Http/Controllers/Api/
├── V1/
│   └── InvoiceController.php     # Move here only when V2 exists
└── V2/
    └── InvoiceController.php

• Domain layer is shared — Actions, Models, Enums are the same across V1 and V2
• Only version what changes — If V2 only changes Invoices, don't copy Customers
• Routes per version —

  routes/api_v1.php

  ,

  routes/api_v2.php

• Deprecate, don't delete — Keep V1 running as long as there are consumers

references/application-layer.md

Naming Conventions

*Action

CreateInvoiceAction

*Data

InvoiceData

Invoice

*QueryBuilder

InvoiceQueryBuilder

*Collection

InvoiceLineCollection

*Status

*Type

InvoiceStatus

*Event

InvoiceCreatedEvent

*Exception

InvalidTransitionException

*Controller

InvoiceController

*IndexQuery

InvoiceIndexQuery

*Resource

InvoiceResource

Store*Request

Update*Request

StoreInvoiceRequest

*Job

SendInvoiceMailJob

Core Principles

1. Actions — Classes with an

   execute()

   method. Represent user stories. Compose via constructor injection. Primary place for business logic.
2. Lean Models — Only relationships, casts, custom QueryBuilders, and custom Collections. No business logic.
3. Data Objects — Use typed

   readonly

   classes (pure PHP 8.3+) only when data comes from multiple sources or the Action is reused across contexts. For simple controller -> action flows, passing the Request or individual parameters is fine.
4. Enums with methods — Replace the state pattern in most cases. Include

   color()

   ,

   label()

   ,

   canTransitionTo()

   directly in the enum. Transitions are done via Actions.
5. Jobs are infrastructure — Manage queues and retries. Business logic stays in Actions called from

   handle()

   .
6. Don't fight the framework — Use standard

   app/

   , standard namespaces, standard artisan. The only addition is

   Domain/

   .

Cross-Domain Communication

Rules

Direct Import (models, enums, preconditions)

namespace App\Domain\Invoice;

use App\Domain\Customer\Customer;

class CreateInvoiceAction
{
    public function execute(InvoiceData $data, Customer $customer): Invoice
    {
        if (! $customer->isActive()) {
            throw new \App\Domain\Customer\InactiveCustomerException();
        }

        return Invoice::create([
            'customer_id' => $customer->id,
            'number' => $data->number,
        ]);
    }
}

Orchestration (needs the result, must be atomic)

class CheckoutController
{
    public function store(CheckoutRequest $request)
    {
        return DB::transaction(function () use ($request) {
            $invoice = app(CreateInvoiceAction::class)->execute($invoiceData);
            $payment = app(ProcessPaymentAction::class)->execute($invoice, $paymentData);

            return new CheckoutResource($invoice, $payment);
        });
    }
}

Events (side effects, reactions)

class CreateInvoiceAction
{
    public function execute(InvoiceData $data): Invoice
    {
        $invoice = Invoice::create([...]);
        event(new InvoiceCreatedEvent($invoice));

        return $invoice;
    }
}

// Another domain reacts via listener — no direct coupling
class ReconcilePaymentListener
{
    public function handle(InvoiceCreatedEvent $event): void
    {
        app(ReconcilePaymentAction::class)->execute($event->invoice);
    }
}

What's Prohibited

• Circular dependencies — If A calls B and B calls A, extract to

  Domain/Shared/

  or use events
• Side effects disguised as direct calls — If the caller doesn't need the result, it should be an event

Domain Service Providers

app/Providers/
├── InvoiceServiceProvider.php
└── CustomerServiceProvider.php

Anti-patterns

• Logic in Models — Models don't calculate, don't send emails, don't validate business rules. That goes in Actions.
• Overly generic Actions —

  ProcessInvoiceAction

  that does 10 things. Prefer specific:

  CreateInvoiceAction

  ,

  MarkInvoiceAsPaidAction

  .
• Repository pattern — Eloquent already is the repository. Use custom QueryBuilders instead.
• Interfaces for everything — Only create interfaces when there are multiple real implementations (e.g., payment gateways).
• Giant Domain/Shared — If

  Shared/

  grows too large, it has code that should be in its own domain.
• DTOs for everything — Don't create a DTO when the controller just passes 2-3 fields to an Action.
• Fighting the framework — Custom Application class, custom autoload, custom directory structure that breaks artisan. If it requires a hack, rethink the approach.

Testing Strategy

• Actions: The most important tests. Pattern: setup -> execute -> assert
• Models: Test custom QueryBuilders and Collections in isolation
• Enums: Test behavior methods and transition rules
• Data Objects: Minimal testing — the type system does the heavy lifting

references/domain-building-blocks.md

Migration Strategy

1. Actions — Extract business logic from controllers and models
2. Domain folders — Group related code when directories become large
3. Data Objects — Replace arrays with typed DTOs where justified
4. Enums with methods — Replace conditionals with behavior in the enum
5. Custom QueryBuilders — Extract complex scopes
6. API Versioning — Structure when the API needs breaking changes

Reference Files

• references/domain-building-blocks.md

  — Data Objects, Actions, Models, Enums, QueryBuilders, Collections, Events, Cross-Domain Communication, Tests

• references/application-layer.md

  — Controllers, Requests, Resources, HTTP Queries, ViewModels, Jobs, API Versioning