Workflow: Add a New CRUD Endpoint

Follow these steps in order. Do not skip steps or reorder them.

Step 0 — Gather Requirements

Before creating any file, confirm:

What is the resource name? (e.g. Car)
What columns does it have and what are their types?
Does it need soft deletes?
Does it need file uploads?
Which routes are needed? (all CRUD, or subset?)
Is authentication required? Which guard?

Detect the project structure first

ls app/

If you see Domain/ → DDD structure — check ls app/Domain/ to confirm folder naming conventions used in the project
If you see Models/, Http/ only → Standard Laravel structure

Path map — resolve once, use throughout all steps

Component	Standard Laravel	DDD
Model	`app/Models/Car.php`	`app/Domain/Car/Models/Car.php`
Filter	`app/Filters/CarFilters.php`	`app/Domain/Car/Filters/CarFilters.php`
Enum	`app/Enums/CarStatusEnum.php`	`app/Domain/Car/Enums/CarStatusEnum.php`
Action	`app/Actions/CreateCarAction.php`	`app/Domain/Car/Actions/CreateCarAction.php`
Policy	`app/Policies/CarPolicy.php`	`app/Domain/Car/Policies/CarPolicy.php`
Form Request	`app/Http/Requests/Car/`	`app/Http/Requests/Application/Car/` (or `Dashboard/Car/`)
Resource	`app/Http/Resources/Car/CarResource.php`	`app/Http/Resources/Application/Car/CarResource.php`
Controller	`app/Http/Controllers/CarController.php`	`app/Http/Controllers/API/Application/Car/CarController.php`

Note: Controllers, Requests, and Resources always stay in app/Http/ regardless of structure — only domain logic moves into app/Domain/.

Step 1 — Model

Follow rules/models.md for the correct structure.

Add all columns to $fillable
Add $casts for booleans, enums, and arrays
Add SoftDeletes if needed
Add relationships
If project uses ULID: add HasUlids trait + $keyType = 'string' + $incrementing = false
Do NOT bind $default_filters yet — do that after creating the Filter (Step 3)

File: app/Models/Car.php — DDD: app/Domain/Car/Models/Car.php

Step 2 — Migration

Create a standard Laravel migration:

Use the project's primary key convention from SKILL.md Project Defaults:

// ULID project
Schema::create('cars', function (Blueprint $table) {
    $table->ulid('id')->primary();
    $table->string('name');
    $table->string('color');
    $table->boolean('is_active')->default(true);
    $table->foreignUlid('user_id')->constrained()->cascadeOnDelete();
    $table->timestamps();
});

// Auto-increment project
Schema::create('cars', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('color');
    $table->boolean('is_active')->default(true);
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->timestamps();
});

Step 3 — Filter

Follow rules/filters.md for the correct structure.

Populate $allowedFilters with columns clients can filter by equality
Populate $allowedSorts with sortable columns (always include created_at)
Populate $columnSearch if text search is needed
Add $allowedIncludes for relationships clients can eager-load
Add custom filter methods for non-trivial conditions

File: app/Filters/CarFilters.php — DDD: app/Domain/Car/Filters/CarFilters.php

Then go back to the Model and bind it:

protected string $default_filters = CarFilters::class;

Step 4 — Enum (if needed)

Follow rules/enums.md for the correct structure. Create one for any fixed-value column (status, type, etc.).

File: app/Enums/CarStatusEnum.php — DDD: app/Domain/Car/Enums/CarStatusEnum.php

Cast it in the Model:

protected $casts = [
    'status' => CarStatusEnum::class,
];

Use it in validation:

'status' => ['required', Rule::in(CarStatusEnum::values())],

Step 5 — Form Requests

Follow rules/requests.md for the correct structure.

Create request: required rules
Update request: same rules but with sometimes prefix for partial updates

Files:

Standard: app/Http/Requests/Car/CreateCarRequest.php
          app/Http/Requests/Car/UpdateCarRequest.php

DDD:      app/Http/Requests/Application/Car/CreateCarRequest.php
          app/Http/Requests/Application/Car/UpdateCarRequest.php
          (use Dashboard/Car/ for admin-facing requests)

Step 6 — Resource

Follow rules/resources.md for the correct structure.

Add all scalar fields to the array
Use $this->whenLoaded('relation') for every relationship
Use dateTimeFormat() for all timestamps
Never add raw DB queries inside toArray()

File: app/Http/Resources/Car/CarResource.php — DDD: app/Http/Resources/Application/Car/CarResource.php

Step 7 — Policy (if authorization needed)

Follow rules/authorization.md. Create a Policy if any endpoint needs ownership or role checks.

Include all applicable methods: viewAny, view, create, update, delete.

File: app/Policies/CarPolicy.php — DDD: app/Domain/Car/Policies/CarPolicy.php

Step 8 — Action (only if needed)

Follow rules/actions.md for the correct structure. Create one only if the operation:

Has multiple distinct steps (even if all on the same model)
Calls an external service (file upload, email, payment)
Needs to be reused across multiple controllers

If it's a simple Model::create($data) — do it directly in the controller. No Action needed.

For external 3rd-party integrations (SMS, payment, etc.), see rules/services.md.

File: app/Actions/CreateCarAction.php — DDD: app/Domain/Car/Actions/CreateCarAction.php

Step 9 — Controller

Follow rules/controllers.md for the correct structure. Use the pattern with a constructor-injected Action/Service/Repository if you created one in Step 8.

Add $this->authorize() on methods that need policy checks
Apply middleware at the route level (not in the constructor — deprecated in Laravel 12)

File: app/Http/Controllers/CarController.php — DDD: app/Http/Controllers/API/Application/Car/CarController.php

Step 10 — Language File

Since all user-facing strings MUST use trans(), create translation keys before writing messages in the controller.

// lang/en/car.php
return [
    'created' => 'Car created successfully.',
    'updated' => 'Car updated successfully.',
    'deleted' => 'Car deleted successfully.',
];

Step 11 — Route

// Full CRUD
Route::apiResource('cars', CarController::class)->middleware('auth:sanctum');

// Or manual registration for partial CRUD
Route::middleware('auth:sanctum')->group(function () {
    Route::get('cars', [CarController::class, 'index']);
    Route::post('cars', [CarController::class, 'store'])->middleware('throttle:10,1');
    Route::get('cars/{car}', [CarController::class, 'show']);
    Route::put('cars/{car}', [CarController::class, 'update']);
    Route::delete('cars/{car}', [CarController::class, 'destroy']);
});

Step 12 — Factory & Test (recommended)

Create a factory:

// database/factories/CarFactory.php
public function definition(): array
{
    return [
        'name'      => fake()->word(),
        'color'     => fake()->safeColorName(),
        'is_active' => true,
        'user_id'   => User::factory(),
    ];
}

Write a feature test covering index, store, show, update, destroy.

Checklist

Before marking the feature done, verify (paths per Step 0 path map):

/new-endpoint