Project Ddd

Domain-Driven Design — Pragmatic Laravel

Restructure Laravel applications into domain-based organisation. Business objectives first — increase revenue, reduce OPEX, ship faster. Not academic DDD, but practical domain separation that your team can maintain.

Philosophy

> "Kita orang meniaga nak increase sales, kurangkan OPEX. Bukan nak berfilasuf pasal kod."

This skill applies DDD where it creates real business value:

• Clear ownership — each domain maps to a business capability, team knows what they own
• Independent velocity — domains can evolve without breaking each other
• Reduced OPEX — less accidental complexity, faster onboarding, fewer cross-cutting bugs
• Business alignment — code structure mirrors how the business actually works

Command Reference

| Command | Description | |---|---| | /project-ddd discover | Interview to identify bounded contexts from business processes | | /project-ddd plan | Generate migration plan from flat Laravel to domain structure | | /project-ddd scaffold | Scaffold a new domain with all layers | | /project-ddd migrate | Move existing code into domain structure (guided, step-by-step) | | /project-ddd wire | Create/update domain service providers and autoloading | | /project-ddd test | Update architecture tests for DDD structure | | /project-ddd audit | Check existing domain structure for violations |

---

1. /project-ddd discover — Domain Discovery

Purpose

Identify bounded contexts by interviewing the user about their business processes, not their code structure.

Interview Questions

Ask in this order:

1. What does your business do? (one sentence)
2. What are the main things your users do? (list activities/workflows)
3. What are your revenue streams? (what gets you paid)
4. What teams or roles exist? (who owns what)
5. What external systems do you integrate with? (payments, email, SMS, APIs)
6. What are your biggest pain points right now? (what breaks, what's slow)

Output

Produce a Domain Map table:

## Domain Map

| Domain | Business Capability | Key Models | Owner | Priority |
|---|---|---|---|---|
| Identity | User auth, roles, profiles | User, Role, Team | Core | High |
| Billing | Subscriptions, invoicing | Plan, Subscription, Invoice | Revenue | High |
| Catalogue | Products, pricing, inventory | Product, Category, Price | Revenue | Medium |
| Fulfilment | Orders, shipping, tracking | Order, Shipment, Tracking | Ops | Medium |
| Notification | Alerts, emails, SMS | Channel, Template, Delivery | Support | Low |
| Shared | Base models, common traits | Base, Activity, Setting | Core | — |

Rules:

• Always include a Shared domain for cross-cutting concerns
• Priority is based on business impact, not code complexity
• Each domain should map to a real business capability, not a technical concept
• If a "domain" is just a CRUD wrapper, it probably belongs inside another domain

---

2. /project-ddd plan — Migration Plan

Purpose

Generate a step-by-step migration plan to move from flat Laravel to domain structure.

Step 1: Analyse Current Structure

Read the project's current app/ directory and categorise:

• Models and their relationships
• Controllers and which models they touch
• Jobs, Events, Listeners and their domain affinity
• Services, Actions and their responsibilities

Step 2: Generate Migration Plan

Produce a numbered task list grouped by domain:

## Migration Plan

### Phase 1: Foundation
- [ ] Task 1: Scaffold src/ directories and configure autoloading
- [ ] Task 2: Move Shared domain models (Base, Activity, Setting)

### Phase 2: Core Domains
- [ ] Task 3: Move [Domain] domain layer (Models, Events, Contracts)
- [ ] Task 4: Move [Domain] application layer (Jobs, Services, Actions)
- [ ] Task 5: Move [Domain] infrastructure layer (Registrars, Exports)

### Phase 3: Supporting Domains
- [ ] Task 6: Move [Domain] domain (Models, Jobs, webhook handlers)
- [ ] Task 7: Move remaining shared infrastructure

### Phase 4: Wiring
- [ ] Task 8: Create domain service providers and clean up AppServiceProvider
- [ ] Task 9: Update architecture tests for DDD structure

### Phase 5: Verification
- [ ] Task 10: Clean up empty directories, full verification

Rules:

• Shared domain first — everything depends on it
• High-priority domains next — business-critical paths
• One domain at a time — never move two domains simultaneously
• Tests must pass after each task — no big-bang migration
• Each task should be a single commit

---

3. /project-ddd scaffold — Scaffold Domain

Purpose

Create a new domain directory structure with all layers.

Interview

Ask the user:

1. Domain name (PascalCase, e.g., Billing, DomainManagement)
2. Key models (what entities live here)
3. Has events? (domain events the business cares about)
4. Has contracts? (interfaces for external dependencies)
5. Has jobs? (async work — processing, syncing)
6. Has actions? (use-case classes following cleaniquecoders/laravel-action)

Generated Structure

src/
└── Domain/
    └── {DomainName}/
        ├── Domain/
        │   ├── Models/
        │   │   └── {Model}.php
        │   ├── Events/
        │   │   └── {Model}Created.php
        │   ├── Contracts/
        │   │   └── {Model}Repository.php
        │   └── ValueObjects/
        │       └── {ValueObject}.php
        ├── Application/
        │   ├── Actions/
        │   │   └── Create{Model}.php
        │   ├── Jobs/
        │   │   └── Process{Model}.php
        │   └── Services/
        │       └── {DomainName}Service.php
        ├── Infrastructure/
        │   ├── Registrars/
        │   │   └── {DomainName}Registrar.php
        │   └── Providers/
        │       └── {DomainName}ServiceProvider.php
        └── Presentation/
            ├── Controllers/
            │   └── {Model}Controller.php
            └── Resources/
                └── {Model}Resource.php

Layer Rules

| Layer | Contains | Depends On | DO NOT | |---|---|---|---| | Domain | Models, Events, Contracts, VOs | Nothing (pure) | Import from Application/Infrastructure | | Application | Actions, Jobs, Services | Domain only | Import from Infrastructure/Presentation | | Infrastructure | Providers, Registrars, Exports | Domain + Application | Contain business logic | | Presentation | Controllers, Resources, Requests | Application | Contain business logic |

Code Templates

Domain Service Provider

expect('Src\Domain\*\Domain')
    ->not->toUse([
        'Illuminate\Support\ServiceProvider',
        'Illuminate\Http',
    ]);

arch('domain models extend base')
    ->expect('Src\Domain\*\Domain\Models')
    ->toExtend('Src\Domain\Shared\Domain\Models\Base');

arch('application layer does not import presentation')
    ->expect('Src\Domain\*\Application')
    ->not->toUse('Src\Domain\*\Presentation');

arch('infrastructure layer does not contain business logic')
    ->expect('Src\Domain\*\Infrastructure')
    ->not->toUse('Src\Domain\*\Domain\Models');

arch('controllers use actions, not models directly')
    ->expect('Src\Domain\*\Presentation\Controllers')
    ->toOnlyUse([
        'Src\Domain\*\Application',
        'Illuminate\Http',
        'Illuminate\Routing',
    ]);

arch('domain events follow naming convention')
    ->expect('Src\Domain\*\Domain\Events')
    ->toHaveSuffix('Event')
    ->orThat()
    ->toMatch('/Created|Updated|Deleted|Activated|Deactivated|Completed/');

arch('value objects are final and readonly')
    ->expect('Src\Domain\*\Domain\ValueObjects')
    ->toBeFinal()
    ->toBeReadonly();

---

7. /project-ddd audit — Domain Audit

Purpose

Check existing domain structure for boundary violations and misplaced code.

Checks

| Check | What It Looks For | |---|---| | Layer violations | Domain importing from Infrastructure/Presentation | | Orphan models | Models in app/Models/ that should be in a domain | | Fat controllers | Controllers with business logic (should use Actions) | | Cross-domain coupling | Domain A directly importing Domain B's models | | Missing providers | Domains without a registered ServiceProvider | | Shared bloat | Too many things in Shared (should be in specific domains) |

Output Format

## DDD Audit Report

### Violations (3)
- Domain\Billing\Domain\Models\Invoice imports from Infrastructure
- Domain\Identity uses Domain\Billing\Domain\Models\Plan directly
- AppServiceProvider still has Billing-specific bindings

### Warnings (2)
- app/Models/Legacy.php not assigned to any domain
- Shared domain has 12 models (consider splitting)

### Healthy (4 domains)
- Identity: clean boundaries
- Billing: clean boundaries
- Catalogue: clean boundaries
- Fulfilment: clean boundaries

---

When NOT to Use DDD

Be honest with the user. DDD adds complexity. Skip it when:

• Small app (< 10 models) — flat Laravel is fine
• Solo developer — you already know where everything is
• CRUD-heavy — if 80% of your app is basic CRUD, DDD is overhead
• Prototype/MVP — ship first, restructure when it hurts

DDD pays off when:

• Multiple teams/devs working on the same codebase
• Business logic is complex (not just CRUD)
• Domains have genuinely different lifecycles
• You need to replace or extract parts independently

---

Reference Files

| File | Description | |---|---| | [references/domain-structure.md](references/domain-structure.md) | Full directory structure template with all layers | | [references/migration-checklist.md](references/migration-checklist.md) | Step-by-step migration checklist with verification gates | | [references/arch-tests.md](references/arch-tests.md) | Complete Pest architecture test suite for DDD boundaries |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nasrulhazim
• Source: nasrulhazim/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.