Forem: Steve McDougall

Building Modern Laravel APIs: The Action Pattern

Steve McDougall — Tue, 14 Apr 2026 09:18:24 +0000

We have a lead ingestion endpoint. Leads arrive, get validated, and get persisted with a pending status and a score of zero. That is the raw intake. Now we need to do something with them.

In this article we are going to build the processing pipeline that transforms a raw lead into something genuinely useful for a sales team. That means AI-powered enrichment via the Laravel AI SDK, a scoring engine that assigns a priority value, and a clean pipeline that wires it all together using composable Action classes.

This is also the article where the Action pattern pays off most visibly. We are not building one thing - we are building three distinct operations and then composing them. The architecture makes that composition clean.

The Processing Pipeline

Before writing any code, let's be clear about what the pipeline does. When a lead arrives it has a pending status. We need to:

Take the raw payload and use AI to infer or fill in missing context - company size, industry, seniority level, anything that was not explicitly provided but can be reasonably inferred. Store that as enriched_data on the lead. Then calculate a score between 0 and 100 based on the enriched data and the scoring rules we care about. Finally update the lead status to enriched and persist both the enriched data and the score.

Three jobs. Three actions. One pipeline action that composes them.

The Laravel AI SDK

The AI SDK is already part of Laravel 13. Install it and publish the config:

composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate

The migration creates the agent_conversations and agent_conversation_messages tables that power the SDK's conversation storage. Configure your provider credentials in .env:

ANTHROPIC_API_KEY=your-key-here

The SDK supports OpenAI, Anthropic, Gemini, and several others. Because we are using the SDK's abstraction layer, swapping providers is a config change, not a code change. That is exactly the kind of flexibility a production application needs.

The Enrichment Agent

The Laravel AI SDK introduces the concept of an Agent - a dedicated PHP class that encapsulates the instructions and output schema for interacting with a language model. Agents implement contracts rather than extend a base class, which keeps them clean and composable.

Generate one:

php artisan make:agent LeadEnrichmentAgent --structured

This creates a class in app/Ai/Agents/ that implements Agent and HasStructuredOutput and uses the Promptable trait. Update it at app/Ai/Agents/LeadEnrichmentAgent.php:

<?php

declare(strict_types=1);

namespace App\Ai\Agents;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;
use Stringable;

final class LeadEnrichmentAgent implements Agent, HasStructuredOutput
{
    use Promptable;

    public function instructions(): Stringable|string
    {
        return <<<PROMPT
        You are a B2B sales intelligence assistant. Given the information about a lead,
        infer and return structured enrichment data that would help a sales team prioritise
        and personalise their outreach.

        Use only the information provided. Do not invent specific facts. Where something
        cannot be reasonably inferred, return null for that field.
        PROMPT;
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'industry' => $schema->string()->nullable()
                ->description('The lead\'s industry sector, e.g. "SaaS", "FinTech", "Healthcare"'),
            'company_size' => $schema->string()->nullable()
                ->description('Estimated company size, e.g. "1-10", "11-50", "51-200", "201-1000", "1000+"'),
            'seniority_level' => $schema->string()->nullable()
                ->description('The lead\'s seniority, e.g. "Junior", "Mid", "Senior", "Director", "C-Level"'),
            'is_decision_maker' => $schema->boolean()->nullable()
                ->description('Whether this lead is likely a decision maker based on their job title'),
            'inferred_pain_points' => $schema->array($schema->string())
                ->description('A list of likely pain points based on the lead\'s role and company context'),
            'enrichment_confidence' => $schema->number()
                ->description('A confidence score from 0.0 to 1.0 indicating how much context was available for enrichment'),
        ];
    }
}

The schema() method receives a JsonSchema $schema instance and returns an array of field definitions. Each field uses the fluent schema builder to describe its type, nullability, and what it represents. The SDK enforces this shape on the model's response, so we always get back a typed, predictable structure rather than freeform text we have to parse and validate ourselves.

The instructions() method defines the system prompt. It tells the model exactly what its job is and explicitly instructs it not to invent specific facts - a critical constraint for a production application where hallucinated data in a CRM causes real problems.

The Enrichment Action

Now the Action that uses the agent.

Create app/Actions/Leads/EnrichLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Ai\Agents\LeadEnrichmentAgent;
use App\Enums\LeadStatus;
use App\Models\Lead;

final readonly class EnrichLead
{
    public function __construct(
        private LeadEnrichmentAgent $agent,
    ) {}

    public function handle(Lead $lead): Lead
    {
        $enrichmentData = (array) $this->agent->prompt(
            $this->buildPrompt($lead),
        );

        $lead->update([
            'enriched_data' => $enrichmentData,
            'status' => LeadStatus::Enriching,
        ]);

        return $lead->fresh();
    }

    private function buildPrompt(Lead $lead): string
    {
        $context = array_filter([
            "Email: {$lead->email}",
            "Name: {$lead->first_name} {$lead->last_name}",
            $lead->company ? "Company: {$lead->company}" : null,
            $lead->job_title ? "Job title: {$lead->job_title}" : null,
            $lead->phone ? "Phone: {$lead->phone}" : null,
            "Lead source: {$lead->source}",
        ]);

        return "Enrich this lead:\n\n" . implode("\n", $context);
    }
}

A few things worth calling out. The agent is injected via the constructor - the container resolves it automatically, which means we can swap the underlying AI provider by changing configuration, not code.

Because LeadEnrichmentAgent implements HasStructuredOutput, calling ->prompt() returns the structured response directly as an object. We cast it to an array for storage in the enriched_data JSON column.

The buildPrompt() method uses array_filter() to remove null values before building the context string. We only send the model data we actually have. Sending empty fields wastes tokens and can confuse the enrichment output.

We set status to LeadStatus::Enriching rather than LeadStatus::Enriched at this stage - the lead is mid-pipeline. The orchestrating ProcessLead action sets it to Enriched once scoring is also complete.

$lead->fresh() at the end returns a fresh model instance from the database with the updated values. Returning the lead rather than void keeps the action composable - the next action in the pipeline receives the updated model.

The Scoring Action

Scoring translates the enriched data into a single integer between 0 and 100 that tells the sales team how much to prioritise this lead. The scoring rules are business logic, not AI - they should be explicit, deterministic, and easy to adjust.

Create app/Actions/Leads/ScoreLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Models\Lead;

final readonly class ScoreLead
{
    public function handle(Lead $lead): Lead
    {
        $score = $this->calculate($lead);

        $lead->update(['score' => $score]);

        return $lead->fresh();
    }

    private function calculate(Lead $lead): int
    {
        $score = 0;
        $enriched = $lead->enriched_data ?? [];

        // Decision makers are high value
        if (($enriched['is_decision_maker'] ?? false) === true) {
            $score += 30;
        }

        // Seniority signals
        $score += match ($enriched['seniority_level'] ?? null) {
            'C-Level' => 25,
            'Director' => 20,
            'Senior' => 10,
            'Mid' => 5,
            default => 0,
        };

        // Company size signals - larger companies are more valuable
        $score += match ($enriched['company_size'] ?? null) {
            '1000+' => 20,
            '201-1000' => 15,
            '51-200' => 10,
            '11-50' => 5,
            default => 0,
        };

        // Reward high enrichment confidence
        $confidence = (float) ($enriched['enrichment_confidence'] ?? 0.0);
        $score += (int) round($confidence * 15);

        // Penalise missing key fields
        if (empty($lead->company)) {
            $score -= 5;
        }

        if (empty($lead->job_title)) {
            $score -= 5;
        }

        return max(0, min(100, $score));
    }
}

The scoring rules are explicit match expressions rather than conditionals buried in if/else chains. That makes them easy to read and easy to adjust when the business decides that company size matters more than seniority, or that a new tier needs adding.

The final max(0, min(100, $score)) clamps the result to the valid range regardless of how the rules interact. Defensive but correct.

The enrichment confidence score from the AI agent feeds directly into the scoring calculation. A lead enriched from a rich dataset of context signals - job title, company, industry - gets a small bonus. A lead where the model had little to work with gets less. This creates a natural feedback loop that rewards more complete inbound data.

The Pipeline Action

Now we compose. ProcessLead is the orchestrating action that runs the full pipeline end-to-end.

Create app/Actions/Leads/ProcessLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Models\Lead;
use Throwable;

final readonly class ProcessLead
{
    public function __construct(
        private EnrichLead $enrichLead,
        private ScoreLead $scoreLead,
    ) {}

    public function handle(Lead $lead): Lead
    {
        try {
            $lead = $this->enrichLead->handle($lead);
            $lead = $this->scoreLead->handle($lead);

            $lead->update(['status' => 'enriched']);

            return $lead->fresh();
        } catch (Throwable $e) {
            $lead->update(['status' => 'failed']);

            throw $e;
        }
    }
}

The pipeline is explicit and linear. Enrich, then score, then mark as enriched. If anything throws, mark the lead as failed and re-throw so the caller can handle it at the appropriate level.

Re-throwing rather than swallowing the exception is important. Swallowing exceptions in pipelines is one of the more reliable ways to create debugging nightmares - leads silently fail and nobody knows why. We catch to set the status, then re-throw so the problem surfaces properly.

The dependency injection chain here is worth appreciating. ProcessLead declares its dependencies. Laravel's container resolves EnrichLead, which in turn declares its dependency on LeadEnrichmentAgent, which the container also resolves. Nothing is manually instantiated. The whole pipeline wires together through the container.

Lead Status as an Enum

As we add more statuses it becomes clear that representing them as raw strings is fragile. Let's introduce a proper enum.

Create app/Enums/LeadStatus.php:

<?php

declare(strict_types=1);

namespace App\Enums;

enum LeadStatus: string
{
    case Pending = 'pending';
    case Enriching = 'enriching';
    case Enriched = 'enriched';
    case Failed = 'failed';
}

Update the Lead model to cast the status column to this enum:

protected function casts(): array
{
    return [
        'raw_payload' => 'array',
        'enriched_data' => 'array',
        'score' => 'integer',
        'status' => LeadStatus::class,
    ];
}

Update the IngestLead action to use the enum:

return Lead::create([
    ...$payload->toArray(),
    'raw_payload' => $payload->toArray(),
    'status' => LeadStatus::Pending,
    'score' => 0,
]);

And update ProcessLead and EnrichLead to use the enum constants rather than raw strings:

// In EnrichLead
$lead->update([
    'enriched_data' => $enrichmentData,
    'status' => LeadStatus::Enriching,
]);

// In ProcessLead
$lead->update(['status' => LeadStatus::Enriched]);
// and on failure:
$lead->update(['status' => LeadStatus::Failed]);

Now if a status value is mistyped or a new case needs adding, the type system catches it rather than silent string comparison failures.

Triggering the Pipeline

The ProcessLead action needs to be called somewhere. For now, we can trigger it directly from the IngestLead action for demonstration - but in Article 9 we will move it to a queued job so the HTTP response is not blocked by the AI enrichment call.

Update app/Actions/Leads/IngestLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Enums\LeadStatus;
use App\Http\Payloads\Leads\StoreLeadPayload;
use App\Models\Lead;

final readonly class IngestLead
{
    public function __construct(
        private ProcessLead $processLead,
    ) {}

    public function handle(StoreLeadPayload $payload): Lead
    {
        $lead = Lead::create([
            ...$payload->toArray(),
            'raw_payload' => $payload->toArray(),
            'status' => LeadStatus::Pending,
            'score' => 0,
        ]);

        return $this->processLead->handle($lead);
    }
}

This is the synchronous version. The controller calls IngestLead, which creates the lead and immediately kicks off enrichment. In a real production environment this would block the HTTP response while the AI call completes - acceptable for now, properly addressed with queues in Article 9.

Configuring the AI Provider

Add your provider key to .env:

ANTHROPIC_API_KEY=your-key-here

The default provider is configured in config/ai.php. For Pulse-Link, Anthropic's Claude is a sensible default given the quality of structured output for enrichment tasks:

'default' => env('AI_PROVIDER', 'anthropic'),

Because we are using the SDK's agent abstraction, switching to OpenAI is a one-line change to the default provider config. The LeadEnrichmentAgent does not know or care which model is running underneath it.

What We Have Now

The Action pattern is doing real work. Three single-responsibility actions - EnrichLead, ScoreLead, and ProcessLead - compose into a pipeline that takes a raw lead from pending to enriched with an AI-generated context payload and a deterministic score.

Each action is independently testable. Swap the agent for a fake in tests, test the scoring logic in isolation, test the pipeline orchestration without touching the AI layer. We will do exactly that in Article 8.

The pipeline is also extensible. Adding a deduplication step, a geographic enrichment step, or a company data lookup is a matter of creating a new action and adding it to ProcessLead. The existing actions do not change.

In the next article we are going to build the lead scoring and prioritisation layer in more depth - turning the enriched data into a ranked list that the sales team can actually work from.

Next: Lead Scoring and Prioritisation - building the ranking engine that surfaces the highest-value leads first using enriched data and configurable scoring rules.

Building Modern Laravel APIs: Authentication with JWT

Steve McDougall — Tue, 14 Apr 2026 09:17:08 +0000

Authentication is one of those things you cannot afford to get wrong. Get it right and it is invisible - it just works, every request is secure, and nobody thinks about it. Get it wrong and you are dealing with security incidents, token leaks, and the kind of technical debt that compounds fast.

In this article we are going to implement JWT authentication properly for Pulse-Link. We already configured the JWT guard in Article 1 and protected our lead routes with auth:api middleware - but right now there is no way to actually get a token. No registration, no login, no refresh. That changes today.

By the end of this article we will have a complete authentication flow: users can register, log in, refresh their tokens, and log out. And it will all follow the same patterns we have established - invokable controllers, Form Request DTOs, Action classes, and Problem+JSON errors.

How JWT Works in This Context

Before we write any code, it is worth being clear about what JWT gives us and why it is the right choice for a pure API application like Pulse-Link.

JSON Web Tokens are self-contained. The token itself contains the user's identity encoded as a signed payload. When a request comes in with a JWT in the Authorization header, the server verifies the signature and decodes the payload - no database lookup required. That stateless nature is exactly what we want in a high-performance ingestion engine.

Compare that to Laravel Sanctum, which stores tokens in the database and does a lookup on every request. For a web application with session-based auth, Sanctum is the right tool. For a pure API that needs to scale horizontally and avoid per-request database overhead, JWT is the better fit.

The php-open-source-saver/jwt-auth package we installed in Article 1 handles all of the cryptographic heavy lifting. Our job is to build the HTTP layer on top of it cleanly.

Preparing the User Model

The JWT package requires the User model to implement the JWTSubject contract. Open app/Models/User.php and update it:

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use PHPOpenSourceSaver\JWTAuth\Contracts\JWTSubject;

#[Fillable('name', 'email', 'password')]
class User extends Authenticatable implements JWTSubject
{
    use HasFactory;
    use HasUlids;
    use Notifiable;

    public function getJWTIdentifier(): mixed
    {
        return $this->getKey();
    }

    public function getJWTCustomClaims(): array
    {
        return [];
    }

    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
        ];
    }
}

A few things to note here. We have added HasUlids - users get ULIDs too, consistent with every other model in the application. We have replaced the $fillable array with the #[Fillable] attribute. And we have implemented getJWTIdentifier() to return the model's primary key, which the package uses as the JWT subject claim.

getJWTCustomClaims() returns an empty array for now - this is where you would add custom data to encode into the token if you needed it. We do not, so we leave it empty.

The Routes

Authentication routes live outside the auth:api middleware group - you cannot require authentication to log in. Add an auth.php route file and register it in routes/api/routes.php.

Create routes/api/auth.php:

<?php

declare(strict_types=1);

use App\Http\Controllers\Auth\V1\LoginController;
use App\Http\Controllers\Auth\V1\LogoutController;
use App\Http\Controllers\Auth\V1\RefreshController;
use App\Http\Controllers\Auth\V1\RegisterController;
use Illuminate\Support\Facades\Route;

Route::post('/register', RegisterController::class)->name('register');
Route::post('/login', LoginController::class)->name('login');

Route::middleware(['auth:api'])->group(function (): void {
    Route::post('/logout', LogoutController::class)->name('logout');
    Route::post('/refresh', RefreshController::class)->name('refresh');
});

Update routes/api/routes.php to include the auth routes:

<?php

declare(strict_types=1);

use Illuminate\Support\Facades\Route;

Route::prefix('v1')->as('v1:')->group(function (): void {
    Route::prefix('auth')->as('auth:')->group(base_path('routes/api/auth.php'));

    Route::prefix('leads')->as('leads:')->middleware(['auth:api'])->group(base_path('routes/api/leads.php'));
});

Notice the auth routes are outside the auth:api middleware group at the top level. Register and login need to be publicly accessible. Logout and refresh need a valid token - that is why they have their own middleware(['auth:api']) group inside the auth route file.

The Payload DTOs

Two payloads needed: one for registration, one for login.

Create app/Http/Payloads/Auth/RegisterPayload.php:

<?php

declare(strict_types=1);

namespace App\Http\Payloads\Auth;

final readonly class RegisterPayload
{
    public function __construct(
        public string $name,
        public string $email,
        public string $password,
    ) {}
}

Create app/Http/Payloads/Auth/LoginPayload.php:

<?php

declare(strict_types=1);

namespace App\Http\Payloads\Auth;

final readonly class LoginPayload
{
    public function __construct(
        public string $email,
        public string $password,
    ) {}
}

These are deliberately minimal. No toArray() method - the auth Actions work with the payload properties directly rather than passing them to a model's create(). Authentication is not a persistence operation in the same way lead ingestion is, so the DTO shape reflects that.

The Form Requests

Create app/Http/Requests/Auth/V1/RegisterRequest.php:

<?php

declare(strict_types=1);

namespace App\Http\Requests\Auth\V1;

use App\Http\Payloads\Auth\RegisterPayload;
use Illuminate\Foundation\Http\FormRequest;

final class RegisterRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'string', 'email', 'max:255', 'unique:users,email'],
            'password' => ['required', 'string', 'min:12', 'confirmed'],
        ];
    }

    public function payload(): RegisterPayload
    {
        return new RegisterPayload(
            name: $this->string('name')->toString(),
            email: $this->string('email')->toString(),
            password: $this->string('password')->toString(),
        );
    }
}

Create app/Http/Requests/Auth/V1/LoginRequest.php:

<?php

declare(strict_types=1);

namespace App\Http\Requests\Auth\V1;

use App\Http\Payloads\Auth\LoginPayload;
use Illuminate\Foundation\Http\FormRequest;

final class LoginRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email' => ['required', 'string', 'email'],
            'password' => ['required', 'string'],
        ];
    }

    public function payload(): LoginPayload
    {
        return new LoginPayload(
            email: $this->string('email')->toString(),
            password: $this->string('password')->toString(),
        );
    }
}

The unique:users,email rule on registration is worth calling out. This gives us a clean validation error before we even try to create the user, rather than letting the database throw a duplicate key exception. The confirmed rule requires a password_confirmation field in the request body - standard practice for registration flows.

The login request is intentionally loose. We validate that the fields are present and correctly shaped, but we do not check the credentials here. That is the Action's job.

The Actions

Four actions, one for each auth operation.

Create app/Actions/Auth/RegisterUser.php:

<?php

declare(strict_types=1);

namespace App\Actions\Auth;

use App\Http\Payloads\Auth\RegisterPayload;
use App\Models\User;
use Illuminate\Support\Facades\Hash;

final readonly class RegisterUser
{
    public function handle(RegisterPayload $payload): User
    {
        return User::query()->create([
            'name' => $payload->name,
            'email' => $payload->email,
            'password' => Hash::make($payload->password),
        ]);
    }
}

Create app/Actions/Auth/LoginUser.php:

<?php

declare(strict_types=1);

namespace App\Actions\Auth;

use App\Http\Payloads\Auth\LoginPayload;
use Illuminate\Support\Facades\Auth;

final readonly class LoginUser
{
    public function handle(LoginPayload $payload): string|false
    {
        return Auth::guard('api')->attempt([
            'email' => $payload->email,
            'password' => $payload->password,
        ]);
    }
}

Create app/Actions/Auth/RefreshToken.php:

<?php

declare(strict_types=1);

namespace App\Actions\Auth;

use Illuminate\Support\Facades\Auth;

final readonly class RefreshToken
{
    public function handle(): string
    {
        return Auth::guard('api')->refresh();
    }
}

Create app/Actions/Auth/LogoutUser.php:

<?php

declare(strict_types=1);

namespace App\Actions\Auth;

use Illuminate\Support\Facades\Auth;

final readonly class LogoutUser
{
    public function handle(): void
    {
        Auth::guard('api')->logout();
    }
}

The LoginUser action returns string|false - a token string on success, or false when the credentials do not match. The controller uses that return value to decide whether to return a 200 with a token or a 401 Problem+JSON response. This is one of the few cases where a falsy return from an action is meaningful rather than exceptional.

Hash::make() in RegisterUser is explicit rather than relying on the model's password cast to handle hashing. The casts() method on the User model does cast password to hashed, which means if you assign a plain-text password directly it gets hashed automatically. But I prefer being explicit about password hashing in the action itself - it makes the intent clear to anyone reading the code without having to trace through the model's cast configuration.

The Token Response

Rather than returning raw token strings in an ad-hoc array from each controller, let's create a consistent token response structure. This is not a full JSON:API resource - token responses are not Eloquent model representations - so we use a simple readonly class.

Create app/Http/Responses/TokenResponse.php:

<?php

declare(strict_types=1);

namespace App\Http\Responses;

use Illuminate\Contracts\Support\Responsable;
use Illuminate\Http\JsonResponse;

final readonly class TokenResponse implements Responsable
{
    public function __construct(
        private string $token,
        private int $status = 200,
    ) {}

    public function toResponse($request): JsonResponse
    {
        return new JsonResponse(
            data: [
                'token' => $this->token,
                'type' => 'Bearer',
            ],
            status: $this->status,
        );
    }
}

Implementing Responsable means we can return a TokenResponse directly from a controller and Laravel handles the rest. The controllers stay clean - no manual new JsonResponse() calls spreading across multiple files.

The Controllers

Now let's wire it all together.

Create app/Http/Controllers/Auth/V1/RegisterController.php:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Auth\V1;

use App\Actions\Auth\LoginUser;
use App\Actions\Auth\RegisterUser;
use App\Http\Requests\Auth\V1\RegisterRequest;
use App\Http\Responses\TokenResponse;

/**
 * @group Authentication
 */
final readonly class RegisterController
{
    public function __construct(
        private RegisterUser $registerUser,
        private LoginUser $loginUser,
    ) {}

    /**
     * Register
     *
     * Register a new user and receive an access token.
     *
     * @bodyParam name string required The user's full name. Example: Jane Smith
     * @bodyParam email string required The user's email address. Example: jane.smith@acme.io
     * @bodyParam password string required The user's password (min 12 characters). Example: super-secret-password
     * @bodyParam password_confirmation string required Password confirmation. Example: super-secret-password
     *
     * @response 201 scenario="Registered" {"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "type": "Bearer"}
     * @response 422 scenario="Validation error" {"type": "https://httpstatuses.com/422", "title": "Unprocessable Entity", "status": 422, "detail": "The given data was invalid.", "errors": {"email": ["The email has already been taken."]}}
     */
    public function __invoke(RegisterRequest $request): TokenResponse
    {
        $user = $this->registerUser->handle(
            payload: $request->payload(),
        );

        $token = $this->loginUser->handle(
            payload: $request->payload(),
        );

        return new TokenResponse(token: $token, status: 201);
    }
}

Create app/Http/Controllers/Auth/V1/LoginController.php:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Auth\V1;

use App\Actions\Auth\LoginUser;
use App\Http\Requests\Auth\V1\LoginRequest;
use App\Http\Responses\TokenResponse;
use Illuminate\Http\JsonResponse;

/**
 * @group Authentication
 */
final readonly class LoginController
{
    public function __construct(
        private LoginUser $loginUser,
    ) {}

    /**
     * Login
     *
     * Authenticate with email and password and receive an access token.
     *
     * @bodyParam email string required The user's email address. Example: jane.smith@acme.io
     * @bodyParam password string required The user's password. Example: super-secret-password
     *
     * @response 200 scenario="Authenticated" {"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "type": "Bearer"}
     * @response 401 scenario="Invalid credentials" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "The provided credentials are incorrect."}
     */
    public function __invoke(LoginRequest $request): TokenResponse|JsonResponse
    {
        $token = $this->loginUser->handle(
            payload: $request->payload(),
        );

        if ($token === false) {
            return new JsonResponse(
                data: [
                    'type' => 'https://httpstatuses.com/401',
                    'title' => 'Unauthenticated',
                    'status' => 401,
                    'detail' => 'The provided credentials are incorrect.',
                ],
                status: 401,
                headers: ['Content-Type' => 'application/problem+json'],
            );
        }

        return new TokenResponse(token: $token);
    }
}

Create app/Http/Controllers/Auth/V1/RefreshController.php:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Auth\V1;

use App\Actions\Auth\RefreshToken;
use App\Http\Responses\TokenResponse;

/**
 * @group Authentication
 */
final readonly class RefreshController
{
    public function __construct(
        private RefreshToken $refreshToken,
    ) {}

    /**
     * Refresh token
     *
     * Exchange a valid token for a fresh one.
     *
     * @response 200 scenario="Refreshed" {"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "type": "Bearer"}
     * @response 401 scenario="Unauthenticated" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "You are not authenticated."}
     */
    public function __invoke(): TokenResponse
    {
        return new TokenResponse(
            token: $this->refreshToken->handle(),
        );
    }
}

Create app/Http/Controllers/Auth/V1/LogoutController.php:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Auth\V1;

use App\Actions\Auth\LogoutUser;
use Illuminate\Http\JsonResponse;

/**
 * @group Authentication
 */
final readonly class LogoutController
{
    public function __construct(
        private LogoutUser $logoutUser,
    ) {}

    /**
     * Logout
     *
     * Invalidate the current token.
     *
     * @response 204 scenario="Logged out" {}
     * @response 401 scenario="Unauthenticated" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "You are not authenticated."}
     */
    public function __invoke(): JsonResponse
    {
        $this->logoutUser->handle();

        return new JsonResponse(status: 204);
    }
}

The RegisterController is the most interesting one. After creating the user it immediately logs them in using the same payload - there is no point making a user complete a login step right after they just registered. They get a token back with a 201 status, ready to start making requests.

The LoginController has a union return type TokenResponse|JsonResponse. This is one of the few places in the application where a controller branches based on business logic. I would normally push that kind of branching into an action, but here the branch point is purely about which HTTP response to return - the action has already done its job and returned a result. The controller is just translating that result into the right response shape.

Testing the Flow

Let's put the whole thing together. Register a new user:

curl -X POST http://localhost:8000/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane.smith@acme.io",
    "password": "super-secret-password",
    "password_confirmation": "super-secret-password"
  }'

You should get a 201 with a token:

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "type": "Bearer"
}

curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@acme.io",
    "password": "super-secret-password"
  }'

Try logging in with wrong credentials to confirm the 401 Problem+JSON response:

curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@acme.io",
    "password": "wrong-password"
  }'

{
    "type": "https://httpstatuses.com/401",
    "title": "Unauthenticated",
    "status": 401,
    "detail": "The provided credentials are incorrect."
}

Refresh a token:

curl -X POST http://localhost:8000/v1/auth/refresh \
  -H "Authorization: Bearer {your-token}"

And log out:

curl -X POST http://localhost:8000/v1/auth/logout \
  -H "Authorization: Bearer {your-token}"

A 204 with an empty body. Clean.

Now go back and use that token against the leads endpoint to confirm end-to-end authentication is working:

curl -X GET http://localhost:8000/v1/leads \
  -H "Authorization: Bearer {your-token}"

You should get a 200 with an empty leads collection rather than a 401. The full auth flow is working.

Run Scribe to pick up the new auth endpoints:

php artisan scribe:generate

What We Have Now

Pulse-Link now has a complete, stateless authentication system. The flow is: register or log in to receive a JWT, include it in the Authorization: Bearer header on every subsequent request, refresh it before it expires, and invalidate it on logout.

Every piece follows the same architecture as the lead ingestion work - invokable controllers, Form Request DTOs, Action classes, clean response types. The auth layer does not feel like a special case bolted onto the side of the application. It feels like the rest of it.

In the next article we are going to go deep on the Action pattern - building the processing and AI enrichment pipeline that takes a lead from pending to enriched. This is where Pulse-Link's core value gets built.

Next: The Action Pattern - building the lead processing and AI enrichment pipeline using Laravel's AI SDK and composable Action classes.

Building Modern Laravel APIs: Routing, Versioning, and API Contracts

Steve McDougall — Tue, 14 Apr 2026 09:17:08 +0000

If there is one decision that will haunt you more than any other in API development, it is not picking the wrong database or choosing the wrong framework. It is shipping a v1 API without any plan for what happens when v1 needs to change.

I have been on the wrong side of that decision. Endpoints that cannot be changed without breaking integrations, clients pinned to behaviour you would love to fix, and a codebase where "we cannot touch that because something depends on it" becomes a recurring conversation. It is a slow, painful kind of technical debt - the kind that compounds quietly until it is everywhere.

In this article we are going to build the routing foundation for Pulse-Link properly. That means a versioned structure from day one, a clean way to signal deprecation when the time comes, and an API contract that stays in sync with the implementation rather than drifting away from it the moment someone forgets to update a YAML file.

How We Structure Routes

In the previous article we set up the project skeleton and configured bootstrap/app.php to load our API routes. The important detail is that we set apiPrefix: '' - there is no /api prefix on our routes. Pulse-Link's endpoints live directly at /v1/.... That is a deliberate choice. The version prefix is enough context. Adding /api in front of it is redundant on an API-only application.

Our route loading in bootstrap/app.php looks like this:

->withRouting(
    api: __DIR__ . '/../routes/api/routes.php',
    apiPrefix: '',
    commands: __DIR__ . '/../routes/console.php',
    health: '/up',
)

The main entry point at routes/api/routes.php is the version grouping layer:

<?php

declare(strict_types=1);

use Illuminate\Support\Facades\Route;

Route::prefix('v1')->as('v1:')->group(function (): void {
    Route::prefix('leads')->as('leads:')->middleware(['auth:api'])->group(base_path('routes/api/leads.php'));
});

A few things are happening here worth unpacking. The as('v1:') call gives every route in the group a name prefix, so our lead routes end up as v1:leads:index, v1:leads:store, and so on. Namespaced route names scale cleanly as the application grows - you can always tell where a named route lives without having to trace the route file.

The base_path() call for loading the resource file is cleaner than require __DIR__ chaining, especially as the number of resource files grows. And because we are applying middleware(['auth:api']) at the group level in routes.php rather than in each resource file, authentication is a routing concern, not a per-resource concern.

The leads route file at routes/api/leads.php stays clean:

<?php

declare(strict_types=1);

use App\Http\Controllers\Leads\V1\IndexController;
use App\Http\Controllers\Leads\V1\ShowController;
use App\Http\Controllers\Leads\V1\StoreController;
use Illuminate\Support\Facades\Route;

Route::get('/', IndexController::class)->name('index');
Route::post('/', StoreController::class)->name('store');
Route::get('/{lead}', ShowController::class)->name('show');

Notice these routes have no middleware, no prefix, and no auth configuration. All of that is handled by the group in routes.php. The resource file only cares about the HTTP method, the path, and the controller. That separation keeps resource files easy to scan and makes it obvious exactly what each route does.

Introducing V2 Without Breaking V1

Let me show you what adding a second version looks like, because it is worth seeing the full picture even before we need it.

When the time comes to introduce a V2 lead endpoint - maybe the response shape changes, maybe we add a new required field - we add a second group in routes.php and deprecate the first:

<?php

declare(strict_types=1);

use Illuminate\Support\Facades\Route;

Route::prefix('v1')->as('v1:')->group(function (): void {
    Route::prefix('leads')
        ->as('leads:')
        ->middleware(['auth:api', 'sunset:2027-01-01'])
        ->group(base_path('routes/api/leads.php'));
});

Route::prefix('v2')->as('v2:')->group(function (): void {
    Route::prefix('leads')
        ->as('leads:')
        ->middleware(['auth:api'])
        ->group(base_path('routes/api/v2/leads.php'));
});

The sunset middleware we built in Article 1 attaches a Sunset header to every V1 response, signalling to clients that this version has a retirement date. V2 controllers live in their own namespace - App\Http\Controllers\Leads\V2\ - so V1 and V2 can evolve independently without any shared state between them.

This is the value of versioning from day one. When V2 arrives, adding it is additive. Nothing breaks. Nothing needs to be untangled. You just add a new group and a new set of controllers.

Stub Controllers

Before we write the OpenAPI contract, let's stub out the three controllers we have referenced in the route file so the application can actually boot. We will fill these in properly in Article 3 - for now they just need to exist.

mkdir -p app/Http/Controllers/Leads/V1

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use Illuminate\Http\JsonResponse;

final class IndexController
{
    public function __invoke(): JsonResponse
    {
        return new JsonResponse(data: [], status: 200);
    }
}

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use Illuminate\Http\JsonResponse;

final class ShowController
{
    public function __invoke(string $lead): JsonResponse
    {
        return new JsonResponse(data: [], status: 200);
    }
}

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class StoreController
{
    public function __invoke(Request $request): JsonResponse
    {
        return new JsonResponse(data: [], status: 201);
    }
}

Simple stubs. The application boots, the routes resolve, and the controllers return an empty response. That is all we need right now.

Documenting the API with Scribe

A hand-written OpenAPI YAML file is a maintenance problem waiting to happen. The moment your implementation drifts from the spec - and it will, because the spec and the code are two separate things that nobody is paid to keep in sync - you have documentation that is confidently wrong. That is worse than no documentation.

The approach I prefer is generating the OpenAPI spec from the code itself, using Laravel Scribe. Scribe reads your routes, controllers, Form Requests, and annotations, and produces a complete OpenAPI 3.1 spec alongside browsable HTML documentation. The spec is always a reflection of what the code actually does, not what you thought it would do when you wrote the YAML six months ago.

Install it as a dev dependency:

composer require --dev knuckleswtf/scribe
php artisan vendor:publish --tag=scribe-config

Then configure config/scribe.php for Pulse-Link. The key settings:

'type' => 'external_laravel',

'title' => 'Pulse-Link API',

'description' => 'A high-performance lead ingestion and enrichment engine.',

'base_url' => env('APP_URL'),

'routes' => [
    [
        'match' => [
            'prefixes' => ['v1/*'],
            'domains' => ['*'],
        ],
        'apply' => [
            'headers' => [
                'Accept' => 'application/json',
                'Authorization' => 'Bearer {token}',
            ],
        ],
    ],
],

'auth' => [
    'enabled' => true,
    'default' => true,
    'in' => 'bearer',
    'name' => 'Authorization',
    'use_value' => env('SCRIBE_AUTH_KEY'),
],

'examples' => [
    'models_source' => ['factoryCreate', 'factoryMake', 'database'],
],

The external_laravel type tells Scribe to write the generated docs to a public/docs directory, which means they are served directly by Laravel at /docs. The routes configuration scopes extraction to our v1/* prefix, so Scribe does not try to document internal or health routes.

Now let's annotate the stub controllers so Scribe has enough context to generate useful output. We use PHPDoc annotations for the high-level description and PHP 8 attributes for the structured metadata.

The IndexController:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use Illuminate\Http\JsonResponse;

/**
 * @group Leads
 */
final class IndexController
{
    /**
     * List leads
     *
     * Returns a paginated list of leads ordered by score descending.
     *
     * @queryParam page integer Page number. Example: 1
     * @queryParam per_page integer Results per page (max 100). Example: 25
     * @queryParam status string Filter by status. Example: pending
     *
     * @response 200 scenario="Success" {"data": [], "meta": {"current_page": 1, "per_page": 25, "total": 0, "last_page": 1}}
     * @response 401 scenario="Unauthenticated" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "You are not authenticated."}
     */
    public function __invoke(): JsonResponse
    {
        return new JsonResponse(data: [], status: 200);
    }
}

The StoreController:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

/**
 * @group Leads
 */
final class StoreController
{
    /**
     * Ingest a lead
     *
     * Accepts raw lead data, validates it, and queues it for AI enrichment.
     *
     * @bodyParam email string required The lead's email address. Example: jane.smith@acme.io
     * @bodyParam first_name string required The lead's first name. Example: Jane
     * @bodyParam last_name string required The lead's last name. Example: Smith
     * @bodyParam company string The lead's company. Example: Acme Corp
     * @bodyParam job_title string The lead's job title. Example: Head of Engineering
     * @bodyParam phone string The lead's phone number. Example: +441234567890
     * @bodyParam source string required The origin of this lead. Example: web-form
     *
     * @response 201 scenario="Created" {"data": {"id": "01JMKP8R2NQZ9F0XVZYS7TDCHK", "type": "leads"}}
     * @response 422 scenario="Validation error" {"type": "https://httpstatuses.com/422", "title": "Unprocessable Entity", "status": 422, "detail": "The given data was invalid.", "errors": {"email": ["The email field is required."]}}
     * @response 401 scenario="Unauthenticated" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "You are not authenticated."}
     */
    public function __invoke(Request $request): JsonResponse
    {
        return new JsonResponse(data: [], status: 201);
    }
}

The ShowController:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use Illuminate\Http\JsonResponse;

/**
 * @group Leads
 */
final class ShowController
{
    /**
     * Get a lead
     *
     * Returns a single lead by its ULID.
     *
     * @urlParam lead string required The lead ULID. Example: 01JMKP8R2NQZ9F0XVZYS7TDCHK
     *
     * @response 200 scenario="Success" {"data": {"id": "01JMKP8R2NQZ9F0XVZYS7TDCHK", "type": "leads"}}
     * @response 404 scenario="Not found" {"type": "https://httpstatuses.com/404", "title": "Not Found", "status": 404, "detail": "The requested resource was not found."}
     * @response 401 scenario="Unauthenticated" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "You are not authenticated."}
     */
    public function __invoke(string $lead): JsonResponse
    {
        return new JsonResponse(data: [], status: 200);
    }
}

The annotations are straightforward. @group clusters related endpoints together in the generated docs. @bodyParam, @queryParam, and @urlParam describe the parameters. @response provides example responses per status code with a named scenario. These are light enough to maintain and rich enough to generate documentation you can actually share with a client.

Once the annotations are in place, generate the docs:

php artisan scribe:generate

Scribe will extract your routes, read the annotations, attempt to call the endpoints with generated example data, and produce both an OpenAPI 3.1 spec at public/docs/openapi.yaml and a browsable HTML reference at /docs. The spec is the output you version-control and share. The HTML is the output you send to whoever is integrating with Pulse-Link.

One thing worth noting: as we build out the real Form Request classes and JSON:API resources in the coming articles, Scribe will pick up validation rules from the Form Requests automatically and use the resource structure to infer response shapes. The annotations we just wrote will become richer without much extra effort - Scribe does the heavy lifting once the implementation exists.

For now, run the generator and confirm it produces clean output:

php artisan scribe:generate
# Documented 3 routes

open public/docs/index.html

That is the contract. Generated from the code, always in sync, and ready to share.

Named Routes in Practice

One last thing worth covering before we move on. The named route structure we set up - v1:leads:index, v1:leads:store, v1:leads:show - is useful beyond just readability.

When we write tests in Article 8, we will generate URLs via route names rather than hardcoded strings:

$response = $this->getJson(route('v1:leads:index'));
$response = $this->postJson(route('v1:leads:store'), $payload);
$response = $this->getJson(route('v1:leads:show', $lead));

If the URL structure ever changes - which it might when we introduce V2 - the tests do not need to be updated. They reference the route by name and the URL resolves automatically. Small habit, significant maintenance win over time.

What We Have Now

At this point Pulse-Link has a routing foundation that is ready to grow. The versioning structure is in place, Scribe is generating a live OpenAPI spec from the code, and the stub controllers mean the application boots cleanly. As we build out the real implementation across the coming articles, the documentation will grow with it automatically.

In the next article we are going to implement the first real feature - lead ingestion. That means building the StoreLeadRequest with a payload() method, the IngestLead action, and the LeadResource JSON:API response. By the end of it, the stub controllers will be gone and Pulse-Link will be accepting its first leads.

Next: Ingesting Leads - building the Form Request DTO, Action class, and JSON:API resource for the lead ingestion endpoint.

Building Modern Laravel APIs: Ingesting Leads

Steve McDougall — Tue, 14 Apr 2026 09:15:23 +0000

This is where Pulse-Link starts to feel real. In the previous two articles we laid the foundation - project structure, routing, versioning, and Scribe for documentation. Now we are going to build the first actual feature: lead ingestion.

By the end of this article, the stub controllers are gone. We will have a working endpoint that accepts a lead payload, validates it, transforms it into a typed DTO, runs it through an Action, and returns a JSON:API formatted response. Every layer of the architecture we talked about in Article 1 will have real code in it.

Let me walk you through how it fits together.

The Shape of a Lead Ingestion Request

Before writing a single class, it is worth being clear about what a valid lead ingestion request looks like. A client sends a JSON body to POST /v1/leads with the raw lead data. Some fields are required - email, first name, last name, and the source of the lead. Everything else is optional context that enriches the record if it is present.

{
    "email": "jane.smith@acme.io",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Corp",
    "job_title": "Head of Engineering",
    "phone": "+441234567890",
    "source": "web-form"
}

That shape drives everything we are about to build. The Form Request validates it. The payload DTO carries it. The Action persists it. The JSON:API resource serialises the result.

The Payload DTO

I always start with the DTO. It is the simplest class in the chain and defining it first forces clarity about what data actually needs to move between layers.

Create app/Http/Payloads/Leads/StoreLeadPayload.php:

<?php

declare(strict_types=1);

namespace App\Http\Payloads\Leads;

final readonly class StoreLeadPayload
{
    public function __construct(
        public string $email,
        public string $firstName,
        public string $lastName,
        public ?string $company,
        public ?string $jobTitle,
        public ?string $phone,
        public string $source,
    ) {}

    public function toArray(): array
    {
        return [
            'email' => $this->email,
            'first_name' => $this->firstName,
            'last_name' => $this->lastName,
            'company' => $this->company,
            'job_title' => $this->jobTitle,
            'phone' => $this->phone,
            'source' => $this->source,
        ];
    }
}

A few things I want to highlight here. The class is final and readonly - it cannot be extended and its properties cannot be mutated after construction. That is exactly what we want from a DTO. The data goes in once, through the constructor, and stays consistent for the lifetime of the object.

The property names use camelCase (firstName, jobTitle) while toArray() maps back to snake_case for persistence. This keeps the PHP side of the code idiomatic while respecting the database column naming convention. It is a small thing, but it removes the jarring mismatch you get when you pepper PHP code with snake_case property names everywhere.

The Form Request

The Form Request has two jobs: validate the incoming payload and produce the typed DTO. Neither job bleeds into the other.

Create app/Http/Requests/Leads/V1/StoreLeadRequest.php:

<?php

declare(strict_types=1);

namespace App\Http\Requests\Leads\V1;

use App\Http\Payloads\Leads\StoreLeadPayload;
use Illuminate\Foundation\Http\FormRequest;

final class StoreLeadRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email' => ['required', 'string', 'email', 'max:255'],
            'first_name' => ['required', 'string', 'max:255'],
            'last_name' => ['required', 'string', 'max:255'],
            'company' => ['nullable', 'string', 'max:255'],
            'job_title' => ['nullable', 'string', 'max:255'],
            'phone' => ['nullable', 'string', 'max:50'],
            'source' => ['required', 'string', 'max:255'],
        ];
    }

    public function payload(): StoreLeadPayload
    {
        return new StoreLeadPayload(
            email: $this->string('email')->toString(),
            firstName: $this->string('first_name')->toString(),
            lastName: $this->string('last_name')->toString(),
            company: $this->string('company')->toString() ?: null,
            jobTitle: $this->string('job_title')->toString() ?: null,
            phone: $this->string('phone')->toString() ?: null,
            source: $this->string('source')->toString(),
        );
    }
}

The payload() method is what separates this from a standard Laravel Form Request. Once validation passes, the controller calls $request->payload() and gets back a StoreLeadPayload instance. From that point on, nothing in the application needs to know about the raw request - it works with the typed DTO.

Notice I am using $this->string() to retrieve values rather than $this->input(). The string() helper returns a Stringable instance, which means we get the fluent string API without having to wrap values manually. Calling ->toString() at the end gives us a plain PHP string. For nullable fields, we coerce an empty Stringable to null with the ternary.

One question that comes up with this pattern: what about the authorize() method? For now it returns true - we are relying on the auth:api middleware at the route level to handle authentication. The authorize() method on a Form Request is for more granular policy checks. We will come back to that when we cover role-based access later in the series.

The Action

The IngestLead action has one job: take a StoreLeadPayload and persist it as a Lead. That is it. No validation, no HTTP concerns, no response formatting.

Create app/Actions/Leads/IngestLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Http\Payloads\Leads\StoreLeadPayload;
use App\Models\Lead;

final readonly class IngestLead
{
    public function handle(StoreLeadPayload $payload): Lead
    {
        return Lead::query()->create([
            ...$payload->toArray(),
            'raw_payload' => $payload->toArray(),
            'status' => 'pending',
            'score' => 0,
        ]);
    }
}

The raw_payload column stores the original data exactly as it arrived. This becomes valuable in Article 9 when we build the enrichment pipeline - if enrichment fails or produces unexpected results, we can always reprocess from the original payload without losing anything.

Setting status to pending and score to 0 here is deliberate. These are not values the client sends - they are the initial state Pulse-Link assigns to every new lead. The client provides the raw data. Pulse-Link decides the initial processing state.

The final readonly combination on the class is a pattern worth following across all Actions. final prevents inheritance - there is no reason to extend a single-purpose action class. readonly signals that the class holds no mutable state. Actions that depend on services get them via constructor injection, and those dependencies are set once and never changed.

The JSON:API Resource

Laravel 13 ships with a first-class JsonApiResource class that handles the JSON:API structure for us. No manual id, type, and attributes wiring - just define your attributes and the framework handles the rest, including setting the Content-Type header to application/vnd.api+json automatically.

Generate it with the --json-api flag:

php artisan make:resource Leads/V1/LeadResource --json-api

This creates a class extending Illuminate\Http\Resources\JsonApi\JsonApiResource. Update it at app/Http/Resources/Leads/V1/LeadResource.php:

<?php

declare(strict_types=1);

namespace App\Http\Resources\Leads\V1;

use App\Models\Lead;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\JsonApi\JsonApiResource;

/**
 * @property-read Lead $resource
 */
final class LeadResource extends JsonApiResource
{
    public function toAttributes(Request $request): array
    {
        return [
            'email' => $this->resource->email,
            'first_name' => $this->resource->first_name,
            'last_name' => $this->resource->last_name,
            'company' => $this->resource->company,
            'job_title' => $this->resource->job_title,
            'phone' => $this->resource->phone,
            'source' => $this->resource->source,
            'score' => $this->resource->score,
            'status' => $this->resource->status,
            'created_at' => $this->resource->created_at,
            'updated_at' => $this->resource->updated_at,
        ];
    }
}

There is quite a bit less boilerplate here compared to a standard JsonResource. The type is derived automatically from the class name - LeadResource becomes leads. The id resolves from the model's primary key. The data wrapping, the attributes nesting, the content type header - all handled by the framework.

The toAttributes() method replaces the old toArray() approach. It returns only the attributes that live inside the attributes object in the JSON:API response. The result looks like this:

{
    "data": {
        "id": "01JMKP8R2NQZ9F0XVZYS7TDCHK",
        "type": "leads",
        "attributes": {
            "email": "jane.smith@acme.io",
            "first_name": "Jane",
            "last_name": "Smith",
            "company": "Acme Corp",
            "job_title": null,
            "phone": null,
            "source": "web-form",
            "score": 0,
            "status": "pending",
            "created_at": "2026-04-10T09:00:00.000000Z",
            "updated_at": "2026-04-10T09:00:00.000000Z"
        }
    }
}

One thing worth updating in AppServiceProvider now that we are using JsonApiResource: remove the JsonResource::withoutWrapping() call. The JsonApiResource class manages its own response structure and the withoutWrapping() call can interfere with it.

public function boot(): void
{
    Model::shouldBeStrict(! app()->isProduction());
}

The @property-read Lead $resource docblock is still worth keeping for IDE autocompletion. A small quality-of-life detail that pays off when you have a dozen resource classes open at once.

Putting It Together: The StoreController

Now we can replace the stub with the real thing.

Update app/Http/Controllers/Leads/V1/StoreController.php:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use App\Actions\Leads\IngestLead;
use App\Http\Requests\Leads\V1\StoreLeadRequest;
use App\Http\Resources\Leads\V1\LeadResource;
use Illuminate\Http\JsonResponse;

/**
 * @group Leads
 */
final readonly class StoreController
{
    public function __construct(
        private IngestLead $ingestLead,
    ) {}

    /**
     * Ingest a lead
     *
     * Accepts raw lead data, validates it, and queues it for AI enrichment.
     *
     * @bodyParam email string required The lead's email address. Example: jane.smith@acme.io
     * @bodyParam first_name string required The lead's first name. Example: Jane
     * @bodyParam last_name string required The lead's last name. Example: Smith
     * @bodyParam company string The lead's company. Example: Acme Corp
     * @bodyParam job_title string The lead's job title. Example: Head of Engineering
     * @bodyParam phone string The lead's phone number. Example: +441234567890
     * @bodyParam source string required The origin of this lead. Example: web-form
     *
     * @response 201 scenario="Created" {"data": {"id": "01JMKP8R2NQZ9F0XVZYS7TDCHK", "type": "leads", "attributes": {"email": "jane.smith@acme.io", "score": 0, "status": "pending"}}}
     * @response 422 scenario="Validation error" {"type": "https://httpstatuses.com/422", "title": "Unprocessable Entity", "status": 422, "detail": "The given data was invalid.", "errors": {"email": ["The email field is required."]}}
     * @response 401 scenario="Unauthenticated" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "You are not authenticated."}
     */
    public function __invoke(StoreLeadRequest $request): JsonResponse
    {
        $lead = $this->ingestLead->handle(
            payload: $request->payload(),
        );

        return (new LeadResource($lead))
            ->response()
            ->setStatusCode(201);
    }
}

The controller stays thin. Three lines of meaningful logic - receive the validated request, call the action with the typed payload, return the resource response.

The ->response()->setStatusCode(201) chain is worth understanding. JsonApiResource extends JsonResource, so calling ->response() returns a ResourceResponse that correctly handles the JSON:API structure and sets the Content-Type: application/vnd.api+json header. We then set the status code to 201 to signal that this was a creation rather than a retrieval. Laravel's container resolves IngestLead via the constructor automatically - no service provider registration needed.

The Index and Show Controllers

While we are here, let's complete the other two controllers so they are no longer stubs. The IndexController returns a paginated collection, and the ShowController returns a single lead.

Update app/Http/Controllers/Leads/V1/IndexController.php:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use App\Http\Resources\Leads\V1\LeadResource;
use App\Models\Lead;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

/**
 * @group Leads
 */
final class IndexController
{
    /**
     * List leads
     *
     * Returns a paginated list of leads ordered by score descending.
     *
     * @queryParam page integer Page number. Example: 1
     * @queryParam per_page integer Results per page (max 100). Example: 25
     * @queryParam status string Filter by status. Example: pending
     *
     * @response 200 scenario="Success" {"data": [], "links": {"first": "...", "last": "...", "prev": null, "next": null}, "meta": {"current_page": 1, "per_page": 25, "total": 0, "last_page": 1}}
     * @response 401 scenario="Unauthenticated" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "You are not authenticated."}
     */
    public function __invoke(Request $request): AnonymousResourceCollection
    {
        $leads = Lead::query()
            ->when(
                $request->string('status')->isNotEmpty(),
                fn ($query) => $query->where('status', $request->string('status')->toString()),
            )
            ->orderByDesc('score')
            ->paginate($request->integer('per_page', 25));

        return LeadResource::collection($leads);
    }
}

Update app/Http/Controllers/Leads/V1/ShowController.php:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use App\Http\Resources\Leads\V1\LeadResource;
use App\Models\Lead;

/**
 * @group Leads
 */
final class ShowController
{
    /**
     * Get a lead
     *
     * Returns a single lead by its ULID.
     *
     * @urlParam lead string required The lead ULID. Example: 01JMKP8R2NQZ9F0XVZYS7TDCHK
     *
     * @response 200 scenario="Success" {"data": {"id": "01JMKP8R2NQZ9F0XVZYS7TDCHK", "type": "leads", "attributes": {"email": "jane.smith@acme.io", "score": 0, "status": "pending"}}}
     * @response 404 scenario="Not found" {"type": "https://httpstatuses.com/404", "title": "Not Found", "status": 404, "detail": "The requested resource was not found."}
     * @response 401 scenario="Unauthenticated" {"type": "https://httpstatuses.com/401", "title": "Unauthenticated", "status": 401, "detail": "You are not authenticated."}
     */
    public function __invoke(Lead $lead): LeadResource
    {
        return new LeadResource($lead);
    }
}

The ShowController uses Laravel's implicit route model binding - the Lead $lead type hint in __invoke tells the framework to resolve the model from the {lead} route parameter automatically. If the ULID does not match a record, Laravel throws a ModelNotFoundException, which our Problem+JSON exception handler in bootstrap/app.php catches and returns as a clean 404 response.

The IndexController uses a when() clause to apply the status filter only when the parameter is present and non-empty. No conditional blocks, no if statements - just a clean fluent query that builds itself based on the request state.

Testing the Endpoint

Let's run a quick manual test to confirm everything is wired up. First, run the migrations if you have not already:

php artisan migrate

Then start the server:

php artisan serve

Send a POST request without a token to confirm Problem+JSON is working:

curl -X POST http://localhost:8000/v1/leads \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.smith@acme.io"}'

You should get a 401 Problem+JSON response. With a valid token, send an incomplete payload:

curl -X POST http://localhost:8000/v1/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your-token}" \
  -d '{"email": "jane.smith@acme.io"}'

This should return a 422 with the missing field errors in the errors object. And with a complete payload:

curl -X POST http://localhost:8000/v1/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your-token}" \
  -d '{
    "email": "jane.smith@acme.io",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Corp",
    "source": "web-form"
  }'

You should get a 201 with the JSON:API formatted lead resource:

{
    "data": {
        "id": "01JMKP8R2NQZ9F0XVZYS7TDCHK",
        "type": "leads",
        "attributes": {
            "email": "jane.smith@acme.io",
            "first_name": "Jane",
            "last_name": "Smith",
            "company": "Acme Corp",
            "job_title": null,
            "phone": null,
            "source": "web-form",
            "score": 0,
            "status": "pending",
            "created_at": "2026-04-10T09:00:00.000000Z",
            "updated_at": "2026-04-10T09:00:00.000000Z"
        }
    }
}

Notice the Content-Type: application/vnd.api+json response header - that comes from JsonApiResource automatically. No extra configuration needed.

Then regenerate the Scribe docs to confirm they reflect the real implementation:

php artisan scribe:generate

The documentation now reflects the actual Form Request validation rules, the real response shape from the LeadResource, and the examples from the controller annotations.

What We Have Built

Three articles in and Pulse-Link is accepting real leads. Here is what the full ingestion flow looks like end-to-end:

The request hits POST /v1/leads. The auth:api middleware validates the JWT. StoreLeadRequest validates the payload and produces a StoreLeadPayload DTO via payload(). The controller passes that DTO to IngestLead::handle(). The action persists the lead with initial pending status and a 0 score, storing the raw payload for future reprocessing. The LeadResource serialises the result into a JSON:API response. The controller returns it with a 201 status.

Every layer has exactly one job. Nothing bleeds into anything else. The architecture we described in Article 1 is now real code.

In the next article we are going to add JWT authentication properly - registration, login, token refresh, and protecting routes beyond the basic auth:api middleware we already have in place.

Next: Authentication with JWT - implementing registration, login, and token refresh for Pulse-Link using php-open-source-saver/jwt-auth.

Building Modern Laravel APIs: Lead Scoring and Prioritisation

Steve McDougall — Tue, 14 Apr 2026 09:15:21 +0000

A lead with a score of zero is not useful to anyone. The whole point of Pulse-Link is that a sales team can open the application and immediately know who to call first. That means scoring has to be meaningful, the prioritisation logic has to be visible and adjustable, and the API needs to surface leads in a way that reflects their value.

In Article 5 we built a basic ScoreLead action with hardcoded scoring rules. In this article we are going to make that scoring engine production-grade - configurable rules, proper score normalisation, a dedicated query layer for prioritised lead retrieval, and the endpoint changes that let clients consume prioritised results effectively.

Why Scoring Belongs in Application Code

Before we get into the implementation, it is worth explaining why the scoring logic lives in PHP rather than in the database or in the AI layer.

The AI enrichment gives us signals - seniority level, company size, decision-maker status. Those are inputs. The scoring rules are business logic that decides how much each signal is worth. Business logic changes. Your sales team will tell you that director-level contacts at mid-market companies are actually more valuable than C-level contacts at small companies because the deal size is larger. Or that a specific industry vertical should score higher because your product fits it better. Those adjustments need to be fast, testable, and visible in code.

If scoring lives in a raw SQL expression or in a prompt to an AI model, it is harder to test, harder to change, and harder to explain to a non-technical stakeholder. In application code with explicit rules, it is all three of those things.

The Scoring Configuration

Rather than hardcoding weights throughout the ScoreLead action, let's move the configuration to a dedicated config file. This makes adjustments a one-line change without touching any PHP logic.

Create config/scoring.php:

<?php

declare(strict_types=1);

return [

    /*
    |--------------------------------------------------------------------------
    | Decision Maker Weight
    |--------------------------------------------------------------------------
    | Points awarded when a lead is identified as a likely decision maker.
    */
    'decision_maker_weight' => env('SCORING_DECISION_MAKER_WEIGHT', 30),

    /*
    |--------------------------------------------------------------------------
    | Seniority Weights
    |--------------------------------------------------------------------------
    | Points awarded per seniority level identified during enrichment.
    */
    'seniority_weights' => [
        'C-Level' => 25,
        'Director' => 20,
        'Senior' => 10,
        'Mid' => 5,
        'Junior' => 0,
    ],

    /*
    |--------------------------------------------------------------------------
    | Company Size Weights
    |--------------------------------------------------------------------------
    | Points awarded per company size band identified during enrichment.
    */
    'company_size_weights' => [
        '1000+' => 20,
        '201-1000' => 15,
        '51-200' => 10,
        '11-50' => 5,
        '1-10' => 0,
    ],

    /*
    |--------------------------------------------------------------------------
    | Enrichment Confidence Weight
    |--------------------------------------------------------------------------
    | Maximum points awarded based on the AI enrichment confidence score.
    | A confidence of 1.0 awards the full weight; 0.0 awards nothing.
    */
    'confidence_weight' => env('SCORING_CONFIDENCE_WEIGHT', 15),

    /*
    |--------------------------------------------------------------------------
    | Completeness Penalties
    |--------------------------------------------------------------------------
    | Points deducted for missing fields that reduce lead quality.
    */
    'missing_company_penalty' => env('SCORING_MISSING_COMPANY_PENALTY', 5),
    'missing_job_title_penalty' => env('SCORING_MISSING_JOB_TITLE_PENALTY', 5),

];

The environment variable overrides for the key weights mean you can tune scoring per deployment without a code change or a redeploy. The per-level seniority and company size arrays stay in config so they are easy to audit and modify.

The Updated ScoreLead Action

Now rewrite app/Actions/Leads/ScoreLead.php to read from config rather than hardcode values:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Enums\LeadStatus;
use App\Models\Lead;

final readonly class ScoreLead
{
    public function handle(Lead $lead): Lead
    {
        $score = $this->calculate($lead);

        $lead->update(['score' => $score]);

        return $lead->fresh();
    }

    private function calculate(Lead $lead): int
    {
        $score = 0;
        $enriched = $lead->enriched_data ?? [];

        $score += $this->decisionMakerScore($enriched);
        $score += $this->seniorityScore($enriched);
        $score += $this->companySizeScore($enriched);
        $score += $this->confidenceScore($enriched);
        $score -= $this->completenessPenalty($lead);

        return max(0, min(100, $score));
    }

    private function decisionMakerScore(array $enriched): int
    {
        if (($enriched['is_decision_maker'] ?? false) === true) {
            return config()->integer('scoring.decision_maker_weight', 30);
        }

        return 0;
    }

    private function seniorityScore(array $enriched): int
    {
        $level = $enriched['seniority_level'] ?? null;
        $weights = config()->array('scoring.seniority_weights', []);

        return (int) ($weights[$level] ?? 0);
    }

    private function companySizeScore(array $enriched): int
    {
        $size = $enriched['company_size'] ?? null;
        $weights = config()->array('scoring.company_size_weights', []);

        return (int) ($weights[$size] ?? 0);
    }

    private function confidenceScore(array $enriched): int
    {
        $confidence = (float) ($enriched['enrichment_confidence'] ?? 0.0);
        $weight = config()->integer('scoring.confidence_weight', 15);

        return (int) round($confidence * $weight);
    }

    private function completenessPenalty(Lead $lead): int
    {
        $penalty = 0;

        if (empty($lead->company)) {
            $penalty += config()->integer('scoring.missing_company_penalty', 5);
        }

        if (empty($lead->job_title)) {
            $penalty += config()->integer('scoring.missing_job_title_penalty', 5);
        }

        return $penalty;
    }
}

Each scoring dimension is now a private method with a single responsibility. Adding a new dimension - say, a geographic score or an industry-vertical bonus - is a matter of adding a config entry and a private method. The calculate() method reads like a specification of what the score is made up of.

The typed config helpers - config()->integer(), config()->array() - are cleaner than casting the return value of config() manually. They also make the intent explicit: this value is expected to be an integer, and if it is missing the default applies. The seniority and company size weights stay as plain array lookups since we need to key into them by the enriched value.

Rescoring Leads

What happens when the scoring rules change? Every existing lead in the database has a stale score. We need a way to rescore them.

Create a command for this:

php artisan make:command RescoreLeads

Update app/Console/Commands/RescoreLeads.php:

<?php

declare(strict_types=1);

namespace App\Console\Commands;

use App\Actions\Leads\ScoreLead;
use App\Enums\LeadStatus;
use App\Models\Lead;
use Illuminate\Console\Command;

final class RescoreLeads extends Command
{
    protected $signature = 'leads:rescore
                            {--status=enriched : Only rescore leads with this status}
                            {--chunk=100 : Number of leads to process per chunk}';

    protected $description = 'Recalculate scores for all enriched leads.';

    public function handle(ScoreLead $scoreLead): int
    {
        $status = LeadStatus::from($this->option('status'));
        $chunk = (int) $this->option('chunk');

        $query = Lead::query()->where('status', $status);
        $total = $query->count();

        if ($total === 0) {
            $this->info('No leads to rescore.');
            return self::SUCCESS;
        }

        $this->info("Rescoring {$total} leads...");

        $bar = $this->output->createProgressBar($total);
        $bar->start();

        $query->chunkById($chunk, function ($leads) use ($scoreLead, $bar): void {
            foreach ($leads as $lead) {
                $scoreLead->handle($lead);
                $bar->advance();
            }
        });

        $bar->finish();
        $this->newLine();
        $this->info('Done.');

        return self::SUCCESS;
    }
}

chunkById() rather than chunk() is important here. When processing large datasets with chunking, chunk() can skip records when records are updated mid-iteration because pagination is offset-based. chunkById() uses the primary key as a cursor, which makes it safe for operations that modify the records being iterated.

The command accepts a --status option so you can rescore all enriched leads or target a specific status. The progress bar gives feedback during long-running rescores.

The Prioritised Lead Query

The IndexController currently orders by score descending. That is the right starting point, but a proper prioritisation endpoint needs more flexibility - filtering by status, minimum score threshold, and the ability to get only the top N leads for a dashboard view.

Create app/Queries/PrioritisedLeadQuery.php:

<?php

declare(strict_types=1);

namespace App\Queries;

use App\Enums\LeadStatus;
use App\Models\Lead;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Database\Eloquent\Builder;

final readonly class PrioritisedLeadQuery
{
    public function __construct(
        private ?LeadStatus $status = LeadStatus::Enriched,
        private int $minimumScore = 0,
        private int $perPage = 25,
    ) {}

    public function paginate(): LengthAwarePaginator
    {
        return $this->baseQuery()->paginate($this->perPage);
    }

    public function top(int $limit): \Illuminate\Database\Eloquent\Collection
    {
        return $this->baseQuery()->limit($limit)->get();
    }

    private function baseQuery(): Builder
    {
        return Lead::query()
            ->when(
                $this->status !== null,
                fn (Builder $query) => $query->where('status', $this->status),
            )
            ->where('score', '>=', $this->minimumScore)
            ->orderByDesc('score')
            ->orderByDesc('created_at');
    }
}

This is a query object rather than a scope or a repository. Query objects are the right tool when the same set of conditions is needed in multiple places and the logic is complex enough to be worth naming. Here we are filtering by status and minimum score, ordering by score with a created_at tiebreaker, and providing two consumption modes - paginated for the index endpoint and a top() method for dashboard summaries.

The secondary orderByDesc('created_at') tiebreaker matters. When multiple leads have the same score, newer leads should surface first - they are more likely to be timely.

Updating the IndexController

Replace the inline query in IndexController with the query object:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use App\Enums\LeadStatus;
use App\Http\Resources\Leads\V1\LeadResource;
use App\Queries\PrioritisedLeadQuery;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Knuckles\Scribe\Attributes\Group;
use Knuckles\Scribe\Attributes\QueryParam;
use Knuckles\Scribe\Attributes\Response;

#[Group('Leads')]
final class IndexController
{
    #[QueryParam('page', 'integer', 'Page number.', required: false, example: 1)]
    #[QueryParam('per_page', 'integer', 'Results per page (max 100).', required: false, example: 25)]
    #[QueryParam('status', 'string', 'Filter by status (pending, enriching, enriched, failed).', required: false, example: 'enriched')]
    #[QueryParam('min_score', 'integer', 'Only return leads with this score or above.', required: false, example: 50)]
    #[Response(['data' => [], 'links' => ['first' => '...', 'last' => '...', 'prev' => null, 'next' => null], 'meta' => ['current_page' => 1, 'per_page' => 25, 'total' => 0, 'last_page' => 1]], 200, 'Success')]
    #[Response(['type' => 'https://httpstatuses.com/401', 'title' => 'Unauthenticated', 'status' => 401, 'detail' => 'You are not authenticated.'], 401, 'Unauthenticated')]
    public function __invoke(Request $request): AnonymousResourceCollection
    {
        $status = $request->string('status')->isNotEmpty()
            ? LeadStatus::tryFrom($request->string('status')->toString())
            : LeadStatus::Enriched;

        $query = new PrioritisedLeadQuery(
            status: $status,
            minimumScore: $request->integer('min_score', 0),
            perPage: min($request->integer('per_page', 25), 100),
        );

        return LeadResource::collection($query->paginate());
    }
}

LeadStatus::tryFrom() rather than LeadStatus::from() is deliberate. from() throws a ValueError if the value is not a valid enum case. tryFrom() returns null instead, which is then handled gracefully - if an invalid status string is passed, it falls back to the default Enriched status rather than throwing an exception. A client sending an unknown status value gets a sensible response rather than a 500.

The min() cap on per_page prevents a client requesting 10,000 records in a single call. Simple but important.

A Top Leads Endpoint

For dashboards and mobile clients that want just the highest-priority leads without pagination overhead, let's add a dedicated endpoint.

Add to routes/api/leads.php:

Route::get('/top', TopController::class)->name('top');

Create app/Http/Controllers/Leads/V1/TopController.php:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Leads\V1;

use App\Http\Resources\Leads\V1\LeadResource;
use App\Queries\PrioritisedLeadQuery;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Knuckles\Scribe\Attributes\Endpoint;
use Knuckles\Scribe\Attributes\Group;
use Knuckles\Scribe\Attributes\QueryParam;
use Knuckles\Scribe\Attributes\Response;

#[Group('Leads')]
final class TopController
{
    #[Endpoint('Top leads', 'Returns the highest-scoring enriched leads without pagination. Useful for dashboard widgets and mobile summary views.')]
    #[QueryParam('limit', 'integer', 'Number of leads to return (max 50, default 10).', required: false, example: 10)]
    #[QueryParam('min_score', 'integer', 'Only return leads with this score or above.', required: false, example: 60)]
    #[Response(['data' => [['id' => '01JMKP8R2NQZ9F0XVZYS7TDCHK', 'type' => 'leads', 'attributes' => ['score' => 85, 'status' => 'enriched']]]], 200, 'Success')]
    #[Response(['type' => 'https://httpstatuses.com/401', 'title' => 'Unauthenticated', 'status' => 401, 'detail' => 'You are not authenticated.'], 401, 'Unauthenticated')]
    public function __invoke(Request $request): AnonymousResourceCollection
    {
        $limit = min($request->integer('limit', 10), 50);

        $query = new PrioritisedLeadQuery(
            minimumScore: $request->integer('min_score', 0),
            perPage: $limit,
        );

        return LeadResource::collection($query->top($limit));
    }
}

The route name follows the same pattern as the rest of the leads routes - it will resolve as v1:leads:top. The limit cap at 50 is intentional; this endpoint is for summary views, not bulk exports.

Updating the LeadResource

Now that leads have meaningful enrichment data, the LeadResource should expose it. Update app/Http/Resources/Leads/V1/LeadResource.php:

<?php

declare(strict_types=1);

namespace App\Http\Resources\Leads\V1;

use App\Models\Lead;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\JsonApi\JsonApiResource;

/**
 * @property-read Lead $resource
 */
final class LeadResource extends JsonApiResource
{
    public function toAttributes(Request $request): array
    {
        return [
            'email' => $this->resource->email,
            'first_name' => $this->resource->first_name,
            'last_name' => $this->resource->last_name,
            'company' => $this->resource->company,
            'job_title' => $this->resource->job_title,
            'phone' => $this->resource->phone,
            'source' => $this->resource->source,
            'score' => $this->resource->score,
            'status' => $this->resource->status,
            'enriched_data' => $this->resource->enriched_data,
            'created_at' => $this->resource->created_at,
            'updated_at' => $this->resource->updated_at,
        ];
    }
}

enriched_data is now part of the response. A client consuming this endpoint can display the AI-inferred industry, seniority, and pain points alongside the score - giving the sales team the context they need to personalise their outreach rather than just a number to rank by.

Regenerating the Docs

With the new endpoint and updated response shape, regenerate Scribe:

php artisan scribe:generate

The top endpoint and the min_score filter on the index endpoint will now appear in the documentation. You will notice we have switched from docblock tags to PHP 8 attributes for the Scribe annotations. The #[Group], #[QueryParam], #[BodyParam], #[UrlParam], and #[Response] attributes from the Knuckles\Scribe\Attributes namespace are equivalent to the old @group, @queryParam, and @response tags, but they are proper PHP - your IDE knows their parameter names, you get autocomplete, and there is no string parsing involved. The #[Group] attribute sits at the class level so it applies to every method in the controller without repeating it per endpoint.

What We Have Now

Pulse-Link now has a scoring engine that is genuinely useful. The rules are visible, configurable, and independently testable. The prioritisation query is reusable across the index and top endpoints. Rescoring is a single Artisan command away when the rules change.

More importantly, the architecture demonstrates something worth internalising: separating concerns at the right level of abstraction produces code that is easier to change. The scoring rules live in config. The calculation logic lives in a single action. The query logic lives in a query object. None of those things know about each other beyond the interface they share.

In the next article we are going to tackle the part of the API that is most visible to clients - response structure, error handling, and making sure every edge case returns something predictable and useful.

Next: Responses and Error Handling - building consistent response structures, handling every error case with Problem+JSON, and making Pulse-Link's API surface genuinely predictable.

Reviewing AI Generated Work

Steve McDougall — Fri, 10 Apr 2026 20:19:07 +0000

Code review has always been one of the most important practices in engineering. It is where mistakes get caught, where knowledge transfers between team members, where standards get enforced, and where the collective understanding of a system gets built and maintained over time. None of that has changed with AI-assisted development. What has changed is the volume, the nature of the output being reviewed, and the specific failure modes that reviewers need to be watching for.

A team that adopts LLM-assisted development without adapting its review practices is a team that is accruing risk faster than it realises. The code looks fine. It passes the tests. It does what was asked of it. And underneath that surface coherence there are patterns, assumptions, and subtle problems that only become visible when something goes wrong in production or when the next engineer tries to extend the code and finds it significantly harder than it should be.

This article is about how to review AI-generated work well - what to look for, how to structure the review process, what the specific failure modes of generated code are, and how to maintain meaningful quality standards when the volume of code being produced has increased significantly.

Let's start with the most important shift in mindset, because without it the tactical advice does not land correctly.

When you review code written by a human colleague, you are reviewing the output of a reasoning process that you can interrogate. If something looks wrong, you can ask why they did it that way. If something is missing, you can assume it was either overlooked or there is a reason they left it out that they can explain. The review is a conversation between two people who share context and who are both trying to make the code better.

When you review AI-generated code, you are reviewing the output of a pattern-matching process that has no understanding of your specific system, your team's conventions, your operational context, or the strategic direction of the product. The model produced something that satisfies the prompt statistically. It has no stake in whether that output is actually correct, actually maintainable, or actually appropriate for your context. There is no reasoning to interrogate, no intent to infer, no colleague to ask for clarification.

That difference changes what a reviewer's job is. With human-written code, the reviewer is a second pair of eyes on a reasoning process that is mostly trustworthy. With AI-generated code, the reviewer is the only reasoning process in the chain. That is a heavier responsibility and it requires a different level of engagement.

The practical implication is that AI-generated code deserves more scrutiny than equivalent human-written code, not less. The temptation is to go the other way - the code looks clean, it is well-structured, it does not have the obvious rough edges that signal a rushed implementation, so it gets a lighter review. That temptation is one of the more reliable ways to introduce subtle problems into a codebase at scale.

The specific failure modes of AI-generated code are worth knowing in detail, because they are different from the failure modes of human-written code and they require different things from reviewers.

Plausible but incorrect logic is the most dangerous failure mode because it is the hardest to catch in a standard review. The model generates code that looks correct, follows the right patterns, and handles the obvious cases - but contains a subtle error in a conditional, an off-by-one in a loop, or a misunderstanding of how a library function behaves in an edge case. The code passes the tests that were generated alongside it because the model made the same incorrect assumption in the test as in the implementation. This is the failure mode that makes test-driven review - evaluating the tests as carefully as the implementation - essential rather than optional.

Context blindness shows up when the generated code technically satisfies the spec but does not fit the larger system it is being integrated into. The model chose a data structure that is inconsistent with how the rest of the codebase handles similar data. It introduced a dependency that duplicates one already in the project. It implemented a pattern that the team has explicitly moved away from. The code is not wrong in isolation - it is wrong in context. Catching this requires reviewers who know the codebase well enough to recognise the inconsistency, which is an argument for ensuring that AI-generated code is reviewed by engineers with genuine system knowledge rather than just whoever is available.

Hallucinated APIs and library behaviour are a known LLM failure mode that is particularly dangerous in code review because the code may work correctly in testing and only fail in specific runtime conditions. The model generates a call to a library method that does not exist, or that exists but does not behave the way the model assumed it does. If the test suite does not exercise that specific path, the error is invisible until production. Reviewing for this means actually checking that the library calls made in generated code correspond to the actual API of the library at the version your project uses - not assuming that because the call looks plausible it is correct.

Security vulnerabilities in AI-generated code follow patterns that are worth understanding. Models trained on large bodies of existing code have absorbed the insecure patterns that exist in that code alongside the secure ones. They will generate SQL queries that are vulnerable to injection if the prompt does not explicitly require parameterised queries. They will generate authentication code that has subtle flaws. They will handle user input without adequate sanitisation if the spec does not explicitly require it. Security review of AI-generated code needs to be treated as a first-class concern, not an afterthought.

Over-engineering is a failure mode that is easy to miss because it does not produce immediate problems. The model generates a solution that is more complex than the problem requires - abstract factory patterns for a problem that needed a simple function, elaborate class hierarchies where a flat module would do, configuration systems where hardcoded values are appropriate for the current stage of the product. The code works but it is harder to understand, harder to modify, and harder to debug than it needed to be. Reviewing for over-engineering means asking whether the complexity of the solution is proportionate to the complexity of the problem, which is a judgment that requires understanding both.

Reviewing against the spec rather than against intuition is the single most important practice change for teams doing AI-assisted development. When you have a well-written spec - and Article 4 in this series was about how to write one - the review question becomes: does this implementation do what the spec says it should do? That is a more precise and more productive question than: does this look right to me?

Reviewing against a spec means going through the spec section by section and verifying that the implementation satisfies each part of it. Interface definitions - does the implementation match the specified interface exactly? Behaviour description - does the implementation handle each case the spec describes? Error handling - does the implementation handle each error condition the spec defines, in the way the spec defines it? Constraints - does the implementation respect the specified performance, security, and convention requirements?

This kind of structured review takes longer than a standard pass but it catches significantly more. It also creates a clear record of what was reviewed and against what criteria, which is useful when a problem surfaces later and you need to understand how it got through.

Testing deserves specific attention in the context of AI-generated code because the tests are often generated alongside the implementation and share the same assumptions. This means the tests can pass while the implementation is wrong, if the wrongness is in an assumption the model made consistently across both.

The response to this is not to distrust tests but to review them as carefully as the implementation - arguably more carefully. Are the tests actually testing the right things? Do they cover the edge cases specified in the spec? Are they testing behaviour or implementation details? Would they catch the failure modes specific to this kind of implementation? A test suite that was generated to match a generated implementation is not the same as a test suite written by someone who understood the expected behaviour independently.

Adding tests that were not generated - tests written by a human reviewer who has read the spec and is thinking about what could go wrong - is one of the most valuable things a reviewer can contribute to an AI-assisted development workflow. It closes the loop that generated tests leave open, and it creates a more robust verification layer that does not share the model's blind spots.

Architectural review is a category of review that most teams treat separately from code review, but which becomes more important as AI-assisted development increases the volume of code being added to a system. An LLM generating implementation code has no visibility into the architectural direction of the system. It will make locally reasonable decisions that can compound into architectural drift if they are not reviewed at a higher level than the individual PR.

Establishing a practice of periodic architectural review - not for every PR but for any significant piece of work that comes out of an AI-assisted cycle - is worth the overhead. The question is not whether each piece of code is correct but whether the collection of decisions made across a cycle is moving the architecture in the right direction. This is a judgment that requires human understanding of the system's current state and intended direction, and it is one that no amount of AI assistance can substitute for.

The human knowledge question is one worth sitting with directly, because it has implications for how teams develop and maintain engineering capability in an AI-assisted world. If the majority of implementation work is being done by AI tools, the engineers who review that work need to have deep enough knowledge of the system to catch the problems those tools introduce. That knowledge comes from doing implementation work, from debugging problems, from building and extending systems over time. If engineers are reviewing AI-generated code without maintaining that implementation depth themselves, the quality of the review will degrade over time as their practical understanding of the system becomes more abstract.

This is not an argument against AI-assisted development. It is an argument for being deliberate about where human engineers invest their implementation effort even when AI tools are available. The engineers who will be most valuable as AI tools become more capable are not the ones who offload the most implementation work but the ones who maintain the deepest understanding of the systems they are responsible for. Review is one of the primary ways that understanding gets built and maintained. Take it seriously.

The volume problem is real and worth acknowledging. When AI-assisted development increases the rate at which code is produced, the review capacity of the team becomes the constraint. More code, same reviewers, same hours. Something has to give, and what usually gives is review quality.

The right response is not to lower the bar for review. It is to be more selective about what gets reviewed at what depth. Significant new functionality, anything touching security or data integrity, anything in a critical path, anything that introduces new patterns to the codebase - these get full spec-based review. Small, self-contained, low-risk changes can move faster. Developing that judgment as a team - being explicit about what warrants deep review rather than leaving it to each reviewer's discretion - is part of building a review practice that scales alongside AI-assisted development.

Review is not overhead. It is the quality control layer that makes AI-assisted development safe to practice at scale. Treat it accordingly.

Next in the series: Redefining Engineering Roles - what senior, mid-level, and junior engineers actually do when LLMs handle a growing share of implementation work, and what that means for how teams hire and develop talent.

Running A Better Table

Steve McDougall — Fri, 10 Apr 2026 20:18:37 +0000

If you have read the previous articles in this series, you have the theory. You understand why sprints are breaking down, you know what Shape Up is trying to do differently, you can write a pitch, and you have a framework for spec-driven development with LLMs. Now we need to talk about the operational reality of actually running the cycle - specifically, the betting table, which is where Shape Up either works or quietly collapses back into something that looks a lot like backlog grooming with different vocabulary.

The betting table is the planning meeting at the heart of Shape Up. It happens at the end of each cooldown period, before the next six-week building cycle begins. The people in the room - typically senior leadership, product, and engineering - look at the available pitches and decide which ones to bet on for the upcoming cycle. That is it. It sounds simple. It is not.

The reason it is not simple is that the betting table is where all of the organisational pressure that Shape Up is designed to resist shows up at once. The urgent request that arrived last week. The stakeholder who has been waiting for their feature for two cycles. The technical work that keeps getting deferred. The sales team who need something before the end of the quarter. Every one of those pressures is real, and every one of them will be in the room with you, either explicitly or implicitly. Running the betting table well means making deliberate decisions in the face of that pressure rather than letting it make the decisions for you.

So let me walk through what running it well actually looks like.

The pitches need to exist before the meeting. This sounds obvious but it is the failure point for a lot of teams adopting Shape Up for the first time. The betting table is a decision meeting, not a brainstorming session. If people are arriving at the betting table without written pitches - with ideas they want to pitch verbally, with half-formed proposals, with "I have been thinking about this thing we should do" - you do not have a betting table. You have a planning meeting dressed up in Shape Up language, and the decisions you make will reflect that.

The shaping work happens during the cooldown, before the betting table convenes. The people responsible for shaping - and this varies by team, but it is typically a combination of senior engineers, product managers, and whoever has the context to think through a problem at the right level of abstraction - spend the cooldown weeks writing and refining pitches. The betting table reviews finished pitches. If a pitch is not written, it does not get bet on. That constraint is a feature, not a bureaucratic hurdle. It ensures that every piece of work that enters a building cycle has been thought through properly rather than improvised.

Who is in the betting table matters and is worth being deliberate about. The people in the room need to have both the authority to commit the team's time and the context to evaluate the pitches being considered. That usually means the most senior product and engineering decision-makers for the area, not a broad representative group. Betting tables that include too many people tend to make decisions by consensus in ways that dilute the quality of the bets. Betting tables that include the wrong people - people without the context or the authority to make real commitments - produce decisions that do not stick.

The meeting itself should be short. Two hours at most for a team of reasonable size, often less. If your betting table is running three or four hours, something is wrong - either the pitches were not well enough shaped going in, the scope of what you are trying to decide is too large, or the decision-making authority in the room is not clear enough.

Each pitch gets a focused discussion. The person who wrote it walks the group through the problem, the shaped solution, the appetite, and the no-gos. The group asks questions, surfaces concerns, and evaluates whether this is the right bet for this cycle. The decision at the end is binary - we bet on this or we do not. No "let's do a partial version of this" unless that partial version is a properly shaped pitch in its own right. No "let's add this to the sprint backlog for the engineers to pick up when they have time." Either it is a bet with a team assigned to it and a clear appetite, or it is not happening this cycle.

The no-carry-over rule is the hardest part of the betting table to hold onto under pressure, and it is the part that matters most. In a traditional backlog, everything that was not done this sprint automatically moves to the next sprint. Nothing is ever explicitly abandoned. The backlog just grows. In Shape Up, a pitch that was not selected at the betting table does not automatically return. If it is still worth doing, it needs to be re-evaluated and probably re-shaped in light of what has been learned since it was first written. If it is not worth re-pitching, it probably was not worth doing in the first place.

This feels brutal when you first encounter it. It feels like good ideas are being lost. What it actually does is force an honest evaluation of whether the work is still the right work, rather than letting it persist in a queue based on the momentum of having been there before. The best teams I have seen running Shape Up treat a pitch that did not get selected not as a failure but as a useful signal - either the shaping needs more work, the timing is not right, or the problem is not as important as it seemed when the pitch was written.

The circuit breaker deserves its own moment because it is the mechanism that makes the appetite constraint real rather than aspirational. In Shape Up, if a project is not done at the end of the six-week cycle, the default is to stop. Not to extend the timeline, not to carry it into the next cycle automatically, but to stop and evaluate. What happened? Was the appetite wrong? Was the pitch under-shaped? Did something unexpected surface during implementation that changed the calculus?

That evaluation might result in a new pitch for a scoped-down version of the work. It might result in a decision that the work is not worth pursuing further. It might result in the same pitch being brought back to the next betting table with the understanding that the appetite needs to be larger. What it does not result in is an automatic extension, because automatic extensions destroy the credibility of the appetite as a constraint and turn the betting table back into a planning meeting where timelines are aspirational rather than real.

In practice, the circuit breaker is one of the more difficult things to hold firm on because there is always a compelling case for why this particular project should be the exception. It is mostly done. The team has context. Stopping now means losing that context and throwing away work. These arguments are usually true and usually irrelevant. The value of the circuit breaker comes precisely from its unconditional nature. An appetite that is sometimes extended is not an appetite. It is an estimate with extra steps.

Protecting the cooldown is the other operational discipline that makes Shape Up work, and it is the one that comes under the most pressure from the outside. Two weeks of cooldown looks, to anyone not inside the methodology, like two weeks of engineering capacity not being fully utilised. The pressure to fill it with urgent requests, to pull engineers onto support tasks, to use it as a catch-up sprint for the things that did not get done in the building cycle - that pressure is constant and it is not entirely unreasonable from the perspective of someone who does not understand what the cooldown is for.

The honest answer to that pressure is this: the cooldown is not free time. It is the time during which the next building cycle gets shaped properly, the technical debt that accumulated during the building cycle gets addressed, the engineers who just spent six weeks on focused delivery work get enough breathing room to think clearly, and the betting table has the preparation it needs to produce good decisions. Cut the cooldown and you cut all of those things. The next cycle starts worse-shaped, with more accumulated debt, with a more depleted team, and with decisions made under less time than they deserve. The cost of the cooldown is visible. The cost of cutting it is distributed across the next several cycles in ways that are harder to see directly.

The question of how to handle genuinely urgent work - the production bug, the security issue, the customer commitment that cannot be moved - is the one that comes up most often when teams are adopting Shape Up. The answer is that Shape Up makes space for urgent work through the cooldown and through the explicit acknowledgment that not every piece of work fits the six-week building cycle model. Small pieces of work that take days rather than weeks can be handled outside the cycle. Genuine emergencies get treated as emergencies regardless of where you are in the cycle. What Shape Up resists is the category of work that feels urgent but is actually just unplanned - the feature that someone wants immediately but that has not been thought through, the scope addition that arrives mid-cycle because someone saw a demo and had new ideas.

That category of pseudo-urgent work is where sprint teams spend a significant amount of their time, and it is one of the primary reasons sprint velocity is so hard to predict. Shape Up's response to it is structural: if it is not a shaped pitch that has been bet on, it does not go into the current cycle. That constraint will feel uncomfortable. It is supposed to. The discomfort is the point - it forces the people generating pseudo-urgent requests to either do the shaping work that would make the request legitimate, or to honestly evaluate whether the request is as urgent as it seemed.

Running a betting table well is fundamentally about holding the methodology with enough conviction to let it do its job. The pressures that push against it are real. The stakeholder who is frustrated. The sales cycle that has created a commitment. The competitor who just shipped something. None of those things go away when you adopt Shape Up. What changes is that you have an explicit framework for deciding what goes into a building cycle, and the discipline to apply it even when the pressure says to make an exception.

The teams that make Shape Up work are the ones that make fewer exceptions, not the ones that make the methodology more flexible. Flexibility is what you had with sprints. Conviction is what makes this different.

Final article in the series: Managing Expectations in the AI Era - how to handle the stakeholders who believe AI makes everything ten times faster, and how to build a realistic narrative around what your team can actually deliver.

Managing Expectations in the AI Era

Steve McDougall — Fri, 10 Apr 2026 20:18:36 +0000

Here is a conversation I suspect a lot of engineering leaders are having right now, in one form or another.

A stakeholder - a product director, a founder, a VP of sales - has read something about how AI makes developers ten times more productive. They have seen demos of entire applications being scaffolded in minutes. They have heard that GitHub Copilot cuts coding time by thirty percent. And now they are sitting across from you asking why, if all of that is true, the roadmap looks basically the same as it did last year.

It is a fair question. And the honest answer is complicated enough that most engineering leaders either oversimplify it in ways that create bigger problems later, or they get defensive in ways that damage the relationship. Neither response serves the team.

This article is about how to have that conversation well. Not how to manage stakeholders in the pejorative sense - not how to deflect or spin or buy yourself time - but how to build a genuinely shared understanding of what AI-assisted development changes, what it does not change, and what realistic expectations look like for a team that is operating thoughtfully in this environment.

Let's start with what is actually true about AI productivity gains, because you cannot have an honest conversation without being honest yourself.

AI tools do make certain categories of engineering work significantly faster. Implementation of well-understood patterns, generation of boilerplate, test scaffolding, documentation, refactoring with clear targets - these things are genuinely faster with good AI tooling than without it. The thirty percent figure from the GitHub Copilot study is probably in the right ballpark for teams using the tools well on the kinds of tasks those tools are suited to.

What the headline numbers do not capture is where the time actually goes in a mature engineering team working on a complex product. Implementation - the writing of code - is rarely the primary bottleneck. Understanding the problem is a bottleneck. Getting alignment on the approach is a bottleneck. Reviewing output for correctness, security, and architectural fit is a bottleneck. Integrating new code with existing systems is a bottleneck. Debugging the subtle problems that AI tools introduce is a bottleneck. Maintaining the system over time as requirements evolve is a bottleneck.

If implementation was fifty percent of the work and AI tools make implementation thirty percent faster, the overall gain is fifteen percent. That is meaningful and worth having. It is not the order-of-magnitude productivity revolution that the demos imply, and closing the gap between those two things is a big part of the expectations conversation.

The demo problem is worth addressing directly because it is the source of a lot of the misalignment. The demos that circulate - an entire web application built in forty minutes, a complex feature implemented from a single prompt - are almost always demonstrations of AI capability on isolated, well-defined, greenfield problems with no existing codebase, no integration constraints, no security requirements, no performance considerations, and no need for the output to be maintained by a team over time.

Real engineering work is none of those things. It is happening in an existing codebase with years of accumulated decisions, dependencies, and constraints. It has to integrate with systems built by other teams. It has to meet security and compliance requirements. It has to be understood and maintained by the engineers who will own it after the person who built it has moved on. The gap between demo conditions and production conditions is where most of the AI productivity premium disappears, and it is a gap that is genuinely hard to convey to someone who has not done engineering work.

The framing I have found most useful for this conversation is to distinguish between implementation speed and delivery speed. AI tools have genuinely improved implementation speed for a meaningful subset of engineering work. Delivery speed - the time from "we decide to build this" to "this is working in production for users" - is determined by a much longer chain of activities, most of which AI tools have not fundamentally changed.

If you can help stakeholders understand that distinction, you have given them a more accurate model of where the productivity gains are and are not, and you have set up a more productive conversation about where investment in AI tooling is likely to pay off versus where the constraints lie elsewhere.

Now let's talk about what changes about expectation management when you are running Shape Up alongside AI-assisted development, because the combination creates specific dynamics worth addressing.

Shape Up already changes the expectation conversation in useful ways. The appetite model gives you a cleaner way to discuss scope and time with stakeholders than sprint velocity does, because it makes the tradeoff explicit upfront. We have six weeks of appetite for this problem. Here is what fits in six weeks. If you want more, the appetite needs to be larger and we need to make a different bet. That clarity is genuinely helpful and it creates a more honest basis for the conversation than "our velocity is X story points per sprint so we can fit Y points of work."

AI-assisted development adds another dimension to that conversation. Because implementation speed has increased for certain kinds of work, stakeholders may reasonably ask whether the appetite for some problems should be smaller than it used to be. That is sometimes true and worth engaging with honestly. A pitch that would have had a six-week appetite two years ago might be achievable in four weeks today for the implementation-heavy parts. It might still need six weeks for the thinking, shaping, reviewing, and integration work. Being specific about which parts of the appetite have changed and which have not is more useful than either claiming that nothing has changed or accepting compressed timelines without examining whether they are realistic.

Managing the expectation that AI tools make every problem faster is one part of this. Managing the expectation that results will be continuously visible is another.

One of the features of sprint methodology that stakeholders have come to rely on is the two-week demo cycle. Every two weeks, something is visible. The team demonstrates progress, stakeholders see movement, and there is a regular heartbeat of visibility that creates a sense of things happening even when the underlying work is complex and slow. Shape Up's six-week cycles do not have that built-in visibility cadence, and the absence of it can create anxiety in organisations that are used to it.

The response to this is not to add artificial demos back into the cycle, which would recreate the overhead without the benefit. It is to give stakeholders a clear picture of what the work is at the start of the cycle and to set explicit expectations about when visibility into the output will be available. "We are betting six weeks on this problem. You will not see a demo in week two because we are still building. You will see something meaningful in week five, at which point there will be time to respond before the cycle closes." That is not less communication - it is better communication, because it is honest about the shape of the work rather than manufacturing artificial milestones.

There is a harder conversation that sits underneath all of this, and it is the one that most engineering leaders avoid because it is uncomfortable. That conversation is about the difference between your team moving faster because of AI tools and the business having more features because of AI tools. Those are not the same thing.

If your team is using AI tools to move faster but you are maintaining the same quality bar, the same review standards, the same architectural discipline, and the same thoughtfulness about what to build - then you are building the same things with less waste, which is genuinely valuable. It means less burnout, more capacity for hard problems, more time for the thinking that generates the most leverage.

That is not the same as having a larger roadmap. If stakeholders are expecting that AI tools will double the number of features shipped per quarter, they are expecting something that requires either cutting the quality and review standards that make AI-assisted development safe, or working the team significantly harder than before. Neither of those is a good outcome, and engineering leaders who let that expectation stand unaddressed will find themselves in a difficult position when the roadmap does not expand at the rate that was implicitly promised.

The conversation worth having instead is about what the team does with the capacity that better tooling creates. Some of it goes into faster, higher-quality implementation. Some of it goes into the thinking and shaping work that produces better decisions about what to build. Some of it goes into the review and architectural work that maintains system quality as AI tools increase the volume of code being produced. Some of it should probably go into investing in the team's own development - learning, experimentation, the work that builds the engineering capability that makes the tooling valuable in the first place.

That is a more nuanced story than "we are ten times more productive now." It is also a more accurate one, and in my experience stakeholders who are engaged with the work as a genuine partner rather than a consumer respond better to nuance than to oversimplification, even when the nuanced version is less exciting.

The practical habits that make expectation management sustainable over time are not complicated, but they require consistency.

Communicate about what is being built and why at the start of each cycle, not just at the end. Give stakeholders the pitch - or a readable version of it - when the bet is placed. That transparency builds trust and it creates a shared basis for the conversation about what changed if the output does not match the expectation.

Be specific about where AI tooling is changing your team's capability and where it is not. "We are moving faster on implementation-heavy work and investing the difference in deeper review and better shaping" is a specific and honest statement. It is also a statement that builds confidence that you are thinking carefully about how the tools are being used, rather than just claiming productivity gains you cannot substantiate.

Push back on compressed timelines that are based on assumptions about AI productivity rather than on what you actually know about the work. The appetite should be set based on the real constraints of the specific problem, not on a general belief that AI tools have made everything faster. Sometimes they have. Sometimes the work is in the parts of the problem where they have not. You need to know which before you commit to a timeline.

And hold the line on quality. The biggest risk in the AI-assisted development era is not that AI tools will make teams less capable. It is that the increased output speed creates pressure to reduce the review, testing, and architectural discipline that keeps that output trustworthy. The teams that manage this well are the ones whose leaders are explicit about what the quality bar is and why maintaining it is not optional even when the pace of production has increased.

Managing expectations in the AI era is not fundamentally different from managing expectations in any other era of significant change in how engineering work gets done. It requires honesty about what has changed, clarity about what has not, and the willingness to have the harder conversation rather than the easier one.

The easier conversation is "AI makes us faster, expect more." The harder conversation is "AI changes the shape of the work in specific ways, here is what that means for what we can deliver and how." The harder conversation is also the one that builds the kind of trust that makes everything else in this series actually work.

This is the final article in the Building Software in the AI Era series. The full series covers why sprints are breaking down, Shape Up as a better operating model, writing pitches, spec-driven development with LLMs, reviewing AI-generated work, redefining engineering roles, running a betting table, and managing the expectations that come with all of it.

Building Modern Laravel APIs: Foundations and Project Structure

Steve McDougall — Fri, 10 Apr 2026 20:18:01 +0000

I have built a lot of Laravel APIs over the years. Some of them were good. Some of them were not. The ones that were not good all had something in common - they started without a clear set of opinions about how the application should be structured, and by the time those opinions became necessary, the codebase was already fighting back.

This series is about doing it right from the start. We are going to build Pulse-Link - a smart lead ingestion engine that receives raw lead data, enriches it using AI, and organises it so a sales team knows exactly who to contact first. But Pulse-Link is the vehicle, not the destination. The patterns, the decisions, and the architectural opinions we establish in this first article are the things you will take to your own projects.

By the end of this series you will have a complete, production-ready Laravel API. Let's start by building the foundation it sits on.

What We Are Building

Pulse-Link is a high-performance ingestion engine. It is not a CRM - it does not try to manage the full lifecycle of a customer relationship. Its job is narrower and more focused: receive lead data from multiple sources, enrich that data using AI to fill in gaps and add context, score each lead based on signals we care about, and surface the highest-priority leads to the sales team.

That scope gives us a domain that is complex enough to justify every pattern we will introduce - authentication, versioning, async processing, AI integration - without being so sprawling that we lose the thread between articles.

The tech stack throughout this series:

PHP 8.5
Laravel 13
PostgreSQL
Laravel AI SDK for enrichment
Laravel JSON:API Resources
PestPHP for testing
JWT authentication via php-open-source-saver/jwt-auth

Let's get the project set up.

Creating the Project

composer create-project laravel/laravel pulse-link
cd pulse-link

The first thing I do with any new Laravel API project is remove everything I do not need. We are building an API, not a web application, so the frontend scaffolding is just noise.

composer remove laravel/pail laravel/sail

Now install the packages we will use throughout the series:

composer require php-open-source-saver/jwt-auth

And our development dependencies:

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Project Structure

This is the part most tutorials skip or gloss over, and it is where a lot of codebases go wrong. The default Laravel structure is fine for small applications. For a production API that will grow over time, we want something more deliberate.

Here is the directory structure we will use throughout this series:

app/
  Actions/
    Leads/
      IngestLead.php
      EnrichLead.php
      ScoreLead.php
  Http/
    Controllers/
      Leads/
        V1/
          IndexController.php
          ShowController.php
          StoreController.php
    Middleware/
      HttpSunset.php
    Requests/
      Leads/
        V1/
          StoreLeadRequest.php
    Resources/
      Leads/
        V1/
          LeadResource.php
  Models/
    Lead.php
    Source.php

routes/
  api/
    routes.php
    leads.php

Each layer has a single responsibility. Controllers handle HTTP. Requests handle validation and produce DTOs. Actions handle business logic. Models handle data access. Nothing bleeds into anything else.

The V1 namespace on controllers and requests is intentional and we will talk about it in detail when we cover versioning. For now, accept that it is there for a good reason.

Core Opinions, Explained

Before we write a single line of business logic, I want to explain the opinions that will run through every article in this series. These are not arbitrary preferences - each one solves a specific problem I have encountered in production.

ULIDs Over Auto-Increment IDs

Auto-increment integer IDs leak information. If your lead endpoint returns an ID of 42, I know you have 42 leads. If it returns 01JMKP8R2NQZ9F0XVZYS7TDCHK, I know nothing about your data volume. ULIDs are also sortable by time, which makes them useful for pagination, and they are safe to generate in application code without a database round-trip.

Laravel ships with first-class ULID support via the HasUlids trait - no extra packages needed. We will use it on every model.

Invokable Controllers

A controller that handles multiple actions is a controller that has too many reasons to change. Single-action invokable controllers keep the responsibility clear - one controller, one HTTP action, one thing it is responsible for doing. The file name tells you exactly what it does: StoreController.php stores a resource. IndexController.php lists resources. No ambiguity.

Form Requests as DTOs

Laravel's Form Request classes are typically used just for validation. We go further. Every Form Request has a payload() method that returns a typed DTO. This means controllers never touch raw request data - they receive a validated, typed object that represents exactly the data the action needs.

This pairs well with the #[Fillable] attribute on models. Validation happens at the Form Request layer, the payload() method transforms that validated data into a typed DTO, and the model's #[Fillable] attribute declares precisely what can be written. Every layer has a clear job, and nothing leaks into anything else.

Action Classes

Business logic lives in Action classes with a handle() method. One action does one thing. IngestLead ingests a lead. EnrichLead enriches it. ScoreLead scores it. This makes logic testable in isolation, reusable across different HTTP contexts, and easy to reason about. We will get deep into this pattern in Article 5.

Problem+JSON Error Responses

RFC 9457 defines a standard format for HTTP error responses. Instead of returning whatever error shape we feel like on a given day, every error from Pulse-Link follows the same structure. Clients can rely on it. Tests can assert against it. It is the kind of consistency that makes an API genuinely pleasant to integrate with.

Versioned Endpoints with HTTP Sunset Headers

We version from day one, not as an afterthought. All routes live under a version prefix. When we eventually introduce a V2, V1 routes get an HTTP Sunset header that tells clients when the old version will be retired. This is how real API lifecycle management works, and building it in from the start costs almost nothing.

Setting Up the Application

Let's configure Pulse-Link properly. Start with config/auth.php to set up JWT as our API guard:

'defaults' => [
    'guard' => 'api',
    'passwords' => 'users',
],

'guards' => [
    'api' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],

Publish the JWT configuration and generate a secret:

php artisan vendor:publish --provider="PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider"
php artisan jwt:secret

Now let's configure AppServiceProvider with the settings that make development and production behaviour more predictable:

<?php

declare(strict_types=1);

namespace App\Providers;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Resources\Json\JsonResource;
use Illuminate\Support\ServiceProvider;

final class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Model::shouldBeStrict(! app()->isProduction());

        JsonResource::withoutWrapping();
    }
}

Model::shouldBeStrict() in non-production environments catches N+1 queries and lazy loading issues during development before they make it to production. JsonResource::withoutWrapping() lets our JSON:API resources control their own wrapping rather than having Laravel add an outer data key that conflicts with the JSON:API spec.

The Lead Model

Let's build the first model. The Lead represents the core entity in Pulse-Link - the raw and enriched data for a single prospect.

First, the migration:

<?php

declare(strict_types=1);

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('leads', function (Blueprint $table): void {
            $table->ulid('id')->primary();
            $table->string('email')->unique();
            $table->string('first_name');
            $table->string('last_name');
            $table->string('company')->nullable();
            $table->string('job_title')->nullable();
            $table->string('phone')->nullable();
            $table->string('source');
            $table->jsonb('raw_payload');
            $table->jsonb('enriched_data')->nullable();
            $table->integer('score')->default(0);
            $table->string('status')->default('pending');
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('leads');
    }
};

A few things worth noting here. We use ulid('id') for the primary key - Laravel 13 has native ULID column support. raw_payload stores the original data exactly as it arrived, which is useful for debugging and reprocessing. enriched_data stores whatever the AI layer adds. score and status drive the prioritisation logic we will build later.

Now the model:

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

#[Fillable(
    'email',
    'first_name',
    'last_name',
    'company',
    'job_title',
    'phone',
    'source',
    'raw_payload',
    'enriched_data',
    'score',
    'status',
)]
final class Lead extends Model
{
    use HasFactory;
    use HasUlids;

    protected function casts(): array
    {
        return [
            'raw_payload' => 'array',
            'enriched_data' => 'array',
            'score' => 'integer',
        ];
    }
}

The #[Fillable] attribute is the modern PHP 8.x way to declare mass-assignable fields - clean, explicit, and right there on the class where you expect to find it. No $fillable array buried in the property list, no Model::unguard() shortcut that removes protection you actually want. Every field that can be written to is declared here, and nothing else gets through.

Routing Structure

Let's set up the routing foundation. First, create the routes directory structure:

mkdir -p routes/api

The main entry point at routes/api/routes.php:

<?php

declare(strict_types=1);

use Illuminate\Support\Facades\Route;

Route::prefix('v1')->as('v1:')->group(function (): void {
    Route::prefix('leads')->as('leads:')->middleware(['auth:api'])->group(base_path('routes/api/leads.php'));
});

And routes/api/leads.php - we will start with a minimal set of routes and expand them across the series:

<?php

declare(strict_types=1);

use App\Http\Controllers\Leads\V1\IndexController;
use App\Http\Controllers\Leads\V1\ShowController;
use App\Http\Controllers\Leads\V1\StoreController;
use Illuminate\Support\Facades\Route;

Route::get('/', IndexController::class)->name('leads.index');
Route::post('/', StoreController::class)->name('leads.store');
Route::get('/{lead}', ShowController::class)->name('leads.show');

->withRouting(
    api: __DIR__ . '/../routes/api/routes.php',
    apiPrefix: '',
    commands: __DIR__ . '/../routes/console.php',
    health: '/up',
)

The HTTP Sunset Middleware

We are building versioning in from day one. When V1 eventually gets superseded by V2, we want to signal that deprecation to clients via the HTTP Sunset header. Let's build the middleware now so it is ready when we need it.

<?php

declare(strict_types=1);

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

final class HttpSunset
{
    public function handle(Request $request, Closure $next, string $date): Response
    {
        $response = $next($request);
        $response->headers->set('Sunset', $date);
        $response->headers->set('Deprecation', 'true');

        return $response;
    }
}

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'sunset' => \App\Http\Middleware\HttpSunset::class,
    ]);
})

When V1 routes need to be deprecated, we add it like this:

Route::middleware(['auth:api', 'sunset:2026-12-31'])->group(function (): void {
    // V1 routes
});

Problem+JSON Error Handling

Consistent error responses are one of the things that separates a good API from a frustrating one. Let's configure the exception handler to return Problem+JSON for every error.

In bootstrap/app.php, add the necessary imports at the top:

use Illuminate\Auth\AuthenticationException;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;

Then inside the ->withExceptions() callback:

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (ValidationException $e, Request $request): JsonResponse {
        return new JsonResponse(
            data: [
                'type' => 'https://httpstatuses.com/422',
                'title' => 'Unprocessable Entity',
                'status' => 422,
                'detail' => 'The given data was invalid.',
                'errors' => $e->errors(),
            ],
            status: 422,
            headers: ['Content-Type' => 'application/problem+json'],
        );
    });

    $exceptions->render(function (AuthenticationException $e, Request $request): JsonResponse {
        return new JsonResponse(
            data : [
                'type' => 'https://httpstatuses.com/401',
                'title' => 'Unauthenticated',
                'status' => 401,
                'detail' => 'You are not authenticated.',
            ],
            status: 401,
            headers: ['Content-Type' => 'application/problem+json'],
        );
    });

    $exceptions->render(function (ModelNotFoundException $e, Request $request): JsonResponse {
        return new JsonResponse(
            data: [
                'type' => 'https://httpstatuses.com/404',
                'title' => 'Not Found',
                'status' => 404,
                'detail' => 'The requested resource was not found.',
            ],
            status: 404,
            headers: ['Content-Type' => 'application/problem+json'],
        );
    });
})

Note the Content-Type: application/problem+json header on every error response. This is RFC 9457 compliant and tells clients they are receiving a structured problem response rather than a generic JSON blob.

Running the Application

Let's make sure everything is wired up correctly. Run the migrations:

php artisan migrate

Start the development server:

php artisan serve

Hit the health endpoint to confirm the application is running:

curl http://localhost:8000/up

You should get a 200 response. If you try to hit a protected route without a token:

curl http://localhost:8000/v1/leads

You should get a properly formatted Problem+JSON 401 response:

{
    "type": "https://httpstatuses.com/401",
    "title": "Unauthenticated",
    "status": 401,
    "detail": "You are not authenticated."
}

That is the foundation working correctly.

What We Have Built

At this point Pulse-Link has a clear structure, sensible defaults, and a set of architectural opinions that will make every subsequent article easier to follow. We have:

A project structure that separates concerns cleanly
JWT configured as the API authentication guard
ULIDs on every model
A versioned routing structure ready for V1 and beyond
HTTP Sunset middleware for graceful API deprecation
Problem+JSON error responses for every error type
Strict model behaviour that catches N+1 issues in development

None of this is complex individually. What makes it valuable is that it is all decided and in place before the business logic arrives. The foundation does not fight you when you start building on it.

In the next article we are going to go deeper on routing, API versioning, and writing an OpenAPI contract for the lead ingestion endpoint before we write a single line of implementation. The contract becomes the spec we build against for the rest of the series.

Next: Routing, Versioning, and API Contracts - building a versioned routing structure and writing an OpenAPI spec for Pulse-Link before the implementation begins.

Redefining Engineering Roles in the AI Era

Steve McDougall — Fri, 10 Apr 2026 20:18:00 +0000

There is a version of the AI-in-engineering conversation that goes like this: LLMs write the code now, so junior engineers are redundant, senior engineers become prompt engineers, and the whole talent pyramid inverts overnight. This version is wrong, but it is wrong in ways that are worth unpacking rather than just dismissing, because the underlying question it is gesturing at is real and important.

How do engineering roles actually change when AI tools handle a meaningful and growing share of implementation work? What does a junior engineer do when the boilerplate they used to write is now generated in seconds? What does a senior engineer do when the implementation work that used to demonstrate their value is increasingly automated? What does a team look like when the relationship between headcount and output has fundamentally shifted?

These are not hypothetical questions. They are questions that engineering leaders and individual engineers are navigating right now, often without a clear framework for thinking about them. This article is an attempt to provide one.

The starting point is understanding what has actually changed and what has not, because the temptation to either overstate or understate the impact of AI tools on engineering work is strong and both directions lead to bad decisions.

What has changed is the cost of implementation. Certain categories of work - scaffolding, boilerplate, straightforward CRUD operations, standard patterns, test generation for well-specified behaviour, documentation of existing code - are significantly cheaper to produce than they were two years ago. An engineer who knows how to use these tools well can produce more of this kind of output in less time. That is real and the implications are real.

What has not changed is the cost of understanding. Understanding a problem deeply enough to know what to build. Understanding a system well enough to know where a new piece of work fits and what constraints it needs to respect. Understanding the product and the users well enough to know whether the thing being built will actually solve the right problem. Understanding the codebase well enough to review AI-generated output critically and catch the failure modes described in the previous article. None of that has gotten cheaper. In some ways it has gotten more expensive, because the volume of output that needs to be understood and evaluated has increased.

This distinction - cheap implementation, expensive understanding - is the key to thinking clearly about how roles change.

Junior engineers have historically learned the craft of software development by doing implementation work. Writing the boilerplate, building the CRUD endpoints, implementing the well-specified feature - these were not just tasks to be completed, they were the primary mechanism through which a junior engineer built up the mental models, the pattern recognition, and the system understanding that eventually made them valuable at a higher level of abstraction.

If that implementation work is increasingly automated, the learning pathway changes. Not disappears - changes. The work that junior engineers now need to do more of is the work of understanding: reading code carefully, reasoning about systems, writing specs and reviewing the output generated against them, debugging the subtle problems that AI tools introduce, and building the deep familiarity with the codebase that makes all of the above possible.

This is genuinely harder to structure than the old model. "Here is a well-defined ticket, implement it" is a clear learning assignment with clear feedback. "Build your understanding of this system by reading, speccing, and reviewing" is a less structured path that requires more active investment from the engineers around the junior person - more pairing, more explanation, more deliberate teaching rather than just assigning implementation tasks and reviewing the output.

Engineering leaders who assume that junior engineers will figure this out on their own will find that their junior engineers are not developing the depth of understanding they need. The learning environment has to be actively redesigned for the new context, not just left to adjust naturally.

Mid-level engineers are where the role change is most significant and, in some ways, most uncomfortable. The mid-level engineer in the traditional model was primarily distinguished by their ability to own implementation work end-to-end - take a complex feature from requirement through deployment with limited guidance. That capability remains valuable, but it is table stakes rather than a differentiator when AI tools can handle the implementation mechanics.

What distinguishes a strong mid-level engineer now is the quality of their judgment. Can they write a spec that is precise enough to produce useful generated output? Can they review that output critically enough to catch the problems it contains? Can they make good architectural decisions about where a new piece of work fits in the system? Can they identify when a generated solution is technically correct but strategically wrong for the product? Can they translate a shaped pitch into a clear implementation plan that a team can execute against?

Those are judgment capabilities, and they develop through a combination of implementation experience, deliberate reflection, and exposure to the kinds of decisions that require them. The path to strong mid-level engineering judgment still runs through doing real implementation work - you cannot develop good judgment about code you have never written. But the weight of the role is shifting from implementation output to implementation judgment, and mid-level engineers who do not make that shift will find their careers plateauing in ways that are hard to articulate.

Senior engineers are experiencing a version of this shift too, but at a different level. The senior engineer's traditional differentiator was technical depth - the ability to solve the hard problems that junior and mid-level engineers could not, to make the architectural decisions that required broad system knowledge, to do the complex implementation that required years of experience to get right.

Technical depth remains essential. What is changing is where it gets applied. The senior engineer who is most valuable in an AI-assisted team is not the one who writes the most code. It is the one who shapes the hardest problems, writes the most precise specs, conducts the most rigorous reviews, and maintains the clearest architectural vision for the systems they are responsible for. Their implementation output may decrease. Their leverage over the team's output should increase.

There is a version of the senior engineer role that does not make this shift - the engineer who continues to measure their contribution primarily by their own implementation output and who uses AI tools to increase that individual output without investing in the team-level leverage that the tools make possible. That engineer becomes less valuable over time, not more, because the team's ability to produce output at scale does not depend on any individual's implementation speed.

The staff engineer role in an AI-assisted engineering organisation looks more important than ever, not less. The work of identifying the right problems, building the technical strategy, maintaining the architectural coherence of systems that are now being extended faster than before, setting the quality and review standards that make AI-assisted development safe - that work is more consequential when the pace of development has increased, not less. Staff engineers who lean into this are well-positioned. Staff engineers who are worried about AI making their expertise obsolete are probably not engaging deeply enough with where their actual leverage is.

Hiring changes in ways that are worth thinking through explicitly, because the attributes that predict success in an AI-assisted engineering team are different from the attributes that traditional engineering interviews are designed to identify.

The ability to write clean code quickly under time pressure - the thing whiteboard interviews and many take-home assessments measure - is less predictive of success than it used to be. The ability to reason clearly about a problem, write a precise spec, ask the right questions, identify what is wrong with a plausible-looking solution, and make good judgment calls under ambiguity - those are more predictive and they are harder to assess in traditional interview formats.

The practical implication is that hiring processes need to change. Technical assessments that ask candidates to implement something from scratch tell you less than assessments that ask candidates to review a piece of generated code and identify its problems, or to take a vague problem description and write a spec that would produce useful generated output. The skills you are hiring for have shifted and the assessments need to reflect that.

Culture fit in an AI-assisted team has a specific dimension worth assessing explicitly: how does this person relate to work they did not do themselves? Engineers who have a strong identity attachment to their individual implementation output - who measure their value by the code they personally wrote - tend to struggle more with AI-assisted development than engineers who identify more with the outcomes they are responsible for. That is not a character flaw, it is a disposition that was actively rewarded in traditional engineering environments. But it is worth understanding before you hire someone into a team where the work looks meaningfully different.

Team structure implications follow from the role changes. If the implementation bottleneck is less constraining than it used to be, the bottlenecks that matter most are understanding, judgment, and review. Those scale differently from implementation. A team of five engineers with strong judgment and review capability can now do the implementation work that previously required ten, but they cannot review and make sense of more output than their collective understanding can handle. Adding more engineers who generate more output without increasing the team's review and judgment capacity makes things worse, not better.

The right shape of an AI-assisted engineering team is probably smaller than the equivalent team from five years ago, with a higher average seniority and a stronger emphasis on the understanding and judgment capabilities described above. That has significant implications for how engineering organisations are sized and structured, and for what the career path looks like for engineers who are entering the field now.

None of this means that engineering as a discipline is becoming less important. It means the most important parts of engineering - the thinking, the judgment, the deep system understanding - are becoming more central rather than less, while the parts that were always somewhat mechanical are being automated. That is probably a good thing for the quality of the work, even if the transition is uncomfortable for people whose identity and compensation are tied to the parts that are changing fastest.

The engineers who will thrive in this environment are the ones who double down on the things that cannot be automated: genuine curiosity about systems, strong judgment about tradeoffs, rigorous thinking about problems, and the ability to maintain deep understanding of complex codebases over time. Those capabilities have always mattered. They now matter more than everything else.

Next in the series: Running a Betting Table - the operational mechanics of Shape Up planning, how to run the cycle, protect the cooldown, and push back on the urgency that is almost never as urgent as it appears.

Spec Driven Development With LLMs

Steve McDougall — Thu, 02 Apr 2026 09:54:59 +0000

There is a pattern that almost every engineer who has worked seriously with LLMs eventually discovers, usually after a few frustrating experiences: the quality of what you get out is determined almost entirely by the quality of what you put in.

This is not a new observation. Every tool reflects the clarity of the instruction given to it. But with LLMs the relationship is more direct and more consequential than most engineers initially expect, because the model is capable enough to produce something plausible regardless of how good your input is. A vague prompt produces confident, coherent, and subtly wrong output. A precise prompt produces something you can actually use. The difference between those two outcomes is the spec.

Spec-driven development is not a new concept either. Writing a clear specification before implementation has been good engineering practice for as long as engineering has existed. What is new is the leverage. When a well-written spec is the input to an LLM, the implementation work that follows is faster, more accurate, and requires significantly less correction than when you start from a rough idea and iterate. The spec is now the highest-leverage thing an engineer writes, and most engineering teams are not treating it that way.

This article is about how to write specifications that work well as LLM inputs - what they need to contain, how to structure them, where the common failure modes are, and how spec-driven development connects to the pitch-based planning approach we covered in the previous article.

Let's start with what a spec is not in this context, because there are a few things it gets confused with.

A spec is not a pitch. The pitch operates at the level of the problem and the shaped solution. It is strategic - it communicates direction and appetite to a team. A spec operates at the level of implementation. It is tactical - it tells you and your tools what to actually build in enough detail that the output can be evaluated against clear criteria. A pitch might describe a notification management feature and its general approach. A spec describes a specific component of that feature: its interface, its behaviour, its error states, its constraints.

A spec is not a ticket. A ticket in most engineering systems is a unit of tracking, not a unit of thinking. "Add notification preferences screen" is a ticket. A spec describes what that screen does, how it behaves under different conditions, what data it works with, what the edge cases are, and what success looks like. The thinking that goes into a good spec is what makes the ticket meaningful rather than just a pointer to work that still needs to be figured out.

A spec is not documentation after the fact. It is a thinking tool that exists before implementation begins, and its value is precisely that it forces the difficult questions to surface before they become expensive problems mid-build.

What a good spec contains depends somewhat on the type of work - a spec for a UI component looks different from a spec for a backend service or a data migration - but there are properties that apply across all of them.

Clarity about what is being built is the foundation. This sounds obvious but it is where most specs fail first. "A service that handles notifications" is not clarity. "A notification delivery service that accepts events from upstream producers via a message queue, applies user preference filters, and dispatches to one or more delivery channels with at-least-once delivery guarantees and idempotency handling on the consumer side" is clarity. The second version tells you what the thing does, how it connects to other things, and what its operational properties are. An LLM given the first version will make decisions about all of those things on your behalf, and some of those decisions will be wrong in ways that are not immediately visible.

Explicit interface definitions matter more than almost anything else when you are using LLM assistance. If you are building a function, describe its signature, its inputs, its outputs, and its error behaviour. If you are building an API endpoint, describe its path, its method, its request shape, its response shape, and its failure modes. If you are building a UI component, describe its props, its states, and the events it emits. The more precisely you define the interface before the LLM generates the implementation, the less time you spend correcting an implementation that works internally but connects incorrectly to everything around it.

This matters specifically for LLM-assisted development because models are very good at implementing something that satisfies an internally consistent spec and very bad at inferring the correct interface from context. If you leave the interface underspecified, the model will make choices that are locally reasonable but that do not match the rest of your system. You will not always catch this immediately, and when you do catch it the fix often requires more rework than if you had specified the interface correctly upfront.

Behaviour under edge cases and error conditions is the part of a spec that most engineers skip and most LLMs handle poorly when left to their own devices. A model given an underspecified prompt will often generate happy-path implementation that handles the common case correctly and ignores everything else. If your spec does not explicitly describe what happens when the input is malformed, when the upstream dependency is unavailable, when the user does not have permission, or when the data is in an unexpected state, you will get an implementation that does not handle those cases - not because the model cannot handle them, but because you did not ask it to.

Write out the edge cases explicitly. Not as an exhaustive list of every possible failure mode, but as a clear description of the categories of error and the expected behaviour for each. "Returns a 422 with a structured error body describing the validation failure" is a useful edge case description. "Handles errors appropriately" is not.

Constraints and non-functional requirements belong in the spec too. Performance expectations, security requirements, dependency versions, coding conventions, testing expectations - these are things that an LLM will make default choices about if you do not specify them, and those default choices may not match your system's actual requirements. If you have a response time budget, say so. If you need the implementation to work with a specific version of a library, say so. If your team has a convention around error handling or logging, describe it. The model has no way to know these things from context unless you tell it.

A practical structure that works well across most implementation specs looks something like this. Start with a brief context section - two or three sentences that place this component in the larger system and explain why it exists. Then the interface definition - inputs, outputs, dependencies. Then the behaviour description - what it does in the normal case, broken down into the meaningful sub-cases. Then the error handling - what happens when things go wrong. Then the constraints - performance, security, conventions. Then the testing expectations - what kinds of tests should exist and what they should verify.

That structure is not a rigid template. Adapt it to the work. A simple utility function does not need a full context section. A complex service with multiple integration points might need more detail in the interface section than the template suggests. The point is to have a consistent habit of thinking that ensures the important things are covered rather than accidentally omitted.

The connection between spec-driven development and the Shape Up methodology from the previous articles is tighter than it might initially appear. In Shape Up, the pitch shapes the problem and the approach at a strategic level. The spec is what happens when a team member takes a piece of the shaped work and thinks through the implementation details before writing code. The two artifacts operate at different levels of abstraction and serve different purposes, but they are part of the same discipline of thinking before building.

One of the things that Shape Up's autonomous team model enables is the kind of focused thinking that good spec writing requires. When a team has six weeks and genuine ownership of a scoped problem, they have the time and the context to write specs that are actually grounded in the real constraints of the work. When a team is running two-week sprints and picking up tickets from a shared backlog, the pressure is toward starting implementation quickly, and the spec is the thing that gets skipped.

There is a version of LLM-assisted development that skips the spec entirely. You describe what you want conversationally, the model generates something, you correct it, it regenerates, and you iterate toward a solution. This works for small, simple, self-contained pieces of work. For anything significant it is slower and produces worse output than writing a clear spec upfront and generating against it. The conversational iteration loop is essentially doing the spec work implicitly, one correction at a time, but without the benefit of having the full picture in one place where you can review it before implementation begins.

Write the spec first. Then generate. Then review the output against the spec rather than against your intuition about what looks right. That review step is important and we will go deeper on it in the next article. For now the key point is that the spec is what makes the review possible - without an explicit description of what the implementation should do, you are reviewing against a fuzzy mental model that is easy to satisfy superficially and hard to hold precisely.

There is also a team benefit to spec writing that is separate from the LLM angle. A spec that exists as a written artifact before implementation begins is something other team members can read, critique, and contribute to. It surfaces disagreements and misunderstandings before they are embedded in code. It creates a shared understanding of what is being built that the implementation alone does not provide. And it is a useful reference during code review - rather than evaluating whether the implementation looks right, reviewers can evaluate whether it satisfies the spec, which is a more precise and more productive question.

This is the aspect of spec-driven development that I think is most undervalued right now. The conversation about LLMs in engineering tends to focus on individual productivity - how much faster can one engineer move with AI assistance. The spec-driven approach creates team-level benefits that compound across the cycle, because it moves the alignment work to the beginning of the implementation rather than distributing it across dozens of review comments and conversations.

Think of the spec as the design review that happens before the code exists rather than after. It is much cheaper to fix a misunderstanding at the spec stage than at the implementation stage, and dramatically cheaper than at the integration stage when the misunderstanding has propagated into multiple parts of the system.

Write the spec. Then build. In that order, every time.

Next in the series: Reviewing AI-Generated Work - how to evaluate code, architecture, and quality when a meaningful portion of your codebase was not written by a human.

Writing Pitches That Work

Steve McDougall — Thu, 02 Apr 2026 09:53:24 +0000

The pitch is the atomic unit of Shape Up. Get it right and the team has everything they need to do good work within the cycle. Get it wrong and you will feel it for six weeks - in misaligned expectations, scope debates that should have happened before the work started, and solutions that technically satisfy the brief but miss the actual problem.

Most teams that adopt Shape Up underinvest in pitch writing. They treat it as a lighter version of a product requirements document, or they go the other direction and write something so vague it gives the team no useful direction at all. Both failure modes are common and both are avoidable once you understand what a pitch is actually trying to do.

A pitch is not a specification. It is not a list of requirements. It is not a design document. It is a shaped proposal - a written artifact that has done enough thinking about a problem to give a team genuine clarity on what they are solving and why, without pre-solving it for them in a way that removes the creative and technical latitude they need to do the work well.

That distinction between shaping and specifying is the most important thing to understand about pitch writing, so let us spend some time on it before getting into the mechanics.

When you specify, you are deciding what the solution looks like before the team has had a chance to engage with the problem. You are drawing wireframes, writing detailed acceptance criteria, and describing behaviour at the level of individual interactions. This feels thorough. It feels like you are setting the team up for success by removing ambiguity. What it actually does is remove the team's ability to find a better solution than the one you already thought of, and it often embeds assumptions that only become visible as problems once implementation starts.

When you shape, you are doing something different. You are thinking hard enough about the problem to understand its boundaries, its constraints, and the general direction of a solution - but stopping short of specifying the details. You are identifying the risks and unknowns that matter, the no-gos that would take the work in the wrong direction, and the properties a good solution needs to have without dictating exactly what form it takes.

The test of whether you have shaped rather than specified is whether the team still has meaningful decisions to make. If you hand the pitch to the team and they essentially have a to-do list to execute, you have over-specified. If you hand them the pitch and they understand the problem, the appetite, the constraints, and the direction, but still need to figure out the best approach - that is a well-shaped pitch.

Now let's get into what a pitch actually contains.

Every pitch worth the name has five components: the problem, the appetite, the solution at the right level of abstraction, the rabbit holes, and the no-gos. These do not have to appear in a rigid template format - a well-written pitch reads more like a short essay than a form - but all five need to be present.

The problem is where most pitches are weakest and where the most leverage is. A vague problem statement produces vague solutions. A precise problem statement - one that describes a specific situation, a specific friction, a specific gap between what exists and what should exist - gives the team something to build against that they can evaluate their work against throughout the cycle.

A weak problem statement: "Users need a better way to manage their notifications."

A stronger problem statement: "Users who receive more than twenty notifications per day are disabling notifications entirely rather than managing them, which means they are missing time-sensitive alerts that affect their workflow. We need a way to let users manage notification volume without losing access to the alerts that actually matter to them."

The difference is not just length. The stronger version identifies who the problem affects, what they are doing as a result of the problem, and what the actual cost of that behaviour is. It gives the team a specific situation to solve for and a way to evaluate whether the solution they build actually addresses it.

The appetite is the honest statement of how much time this work is worth. Not how long you expect it to take - how much time you are willing to spend on it given what you know about its value and strategic importance. Two weeks for a small improvement. Six weeks for something more significant. Be direct and be honest. If the appetite is two weeks, write two weeks and mean it. The appetite is not a soft target that expands when the work turns out to be more complex than expected. It is a constraint that shapes the scope of the solution.

Stating the appetite explicitly also forces an important conversation before the cycle begins. If the team reads the pitch and immediately thinks the problem cannot be meaningfully addressed in the stated appetite, that is a conversation worth having before six weeks of work happens, not after.

The solution section is where the shaping work lives, and it is the hardest part of a pitch to write well. You are trying to communicate enough about the direction and the approach that the team is not starting from zero, without designing the solution so completely that you have made all the meaningful decisions for them.

A few techniques that help here. Breadboarding is the practice of sketching the key components and connections of a solution without specifying its visual design - think of it as a schematic rather than a mockup. You might sketch that there is a notification preferences screen with three distinct categories, that categories can be muted rather than all notifications being turned off, and that there is an activity log so users can see what they missed. That communicates direction without locking in the visual design, the exact interaction model, or the technical implementation.

Fat marker sketches serve a similar purpose for more visual problems. Rough, low-fidelity drawings that capture the general layout and flow without the kind of detail that a real wireframe contains. The roughness is intentional - it signals to the team that the sketch is directional, not prescriptive, and it leaves room for them to find better solutions within the general approach.

The key is to work at the level of components and relationships rather than the level of pixels and interactions. What are the meaningful parts of this solution? How do they connect? What does someone move through as they use it? Those are the questions a good solution section answers without over-answering.

Rabbit holes deserve more attention than they usually get in discussions of Shape Up. A rabbit hole is a part of the problem that looks tractable but might turn out to be much more complex than it appears - the kind of thing that could consume most of a cycle if the team is not explicitly warned about it.

Identifying rabbit holes in a pitch is one of the highest-value things a shaper can do, because it requires actually thinking through the implementation risks before the work starts rather than discovering them mid-cycle when there is less time to respond. It also signals to the team that you have thought about the problem seriously rather than just describing it from a high level.

A rabbit hole might be a technical dependency that is less stable than it appears. It might be an edge case in the data model that looks simple on the surface but branches into complexity once you dig in. It might be an interaction with an existing feature that creates unexpected constraints. Whatever it is, naming it explicitly in the pitch gives the team permission to timebox their investigation of it rather than going deep in search of a perfect solution.

The no-gos are the explicit scope boundaries - the things that are specifically out of scope for this cycle even if they seem related. No-gos are important because they prevent scope creep from a specific direction: the well-intentioned team member who sees adjacent work and pulls it into the cycle because it seems related and they have the context to do it.

No-gos also do something less obvious: they signal that the shaper has thought about what this work is not, which is often as clarifying as knowing what it is. "This does not include email notification preferences, which will be addressed in a separate cycle" is a useful statement because it tells the team where the boundary is and why, and it heads off a conversation that would otherwise happen at an inconvenient moment during implementation.

There is a question that comes up when teams start writing pitches with LLM assistance, which is increasingly common: how do you use a tool like this in the shaping process without ending up with something that is technically complete but fundamentally generic?

The honest answer is that LLMs are useful for some parts of pitch writing and not others. They are useful for refining language, checking that a problem statement is clear to someone without context, generating a list of rabbit holes to consider, and structuring a rough draft that you have already thought through. They are not useful for the actual thinking work of shaping - understanding the specific problem in its specific context, identifying the constraints that matter, and making the judgment calls about where the scope boundary should be.

The pitches that work are the ones where the thinking happened before the writing. If you use an LLM to generate a pitch from a one-line prompt, you will get something that looks like a pitch but lacks the depth of understanding that makes a pitch actually useful. The team will feel that absence during the cycle, even if they cannot always articulate where it is coming from.

Write the hard parts yourself. Use the tools for everything else.

One last thing about pitch writing that does not get said enough: a pitch that does not get selected at the betting table is not a failed pitch. It is a well-spent investment in understanding the problem. The thinking you did to write the pitch - the problem definition, the constraint identification, the risk mapping - is valuable regardless of whether this specific version of the work happens this cycle. If the pitch comes back at the next betting table, the thinking is still there and the pitch can be refined rather than rewritten. If the problem turns out to have changed or resolved itself, the thinking helped you understand that faster than you would have otherwise.

Treat pitches as a practice, not a transaction. Write them carefully, get better at writing them over time, and use the betting table's response to them as feedback on whether you are shaping at the right level of abstraction. That feedback loop, over several cycles, is what turns pitch writing from an uncomfortable new process into one of the most clarifying things an engineering organisation can do.

Next in the series: Spec-Driven Development with LLMs - how to write specifications that produce useful output from AI tools, and why the quality of your spec is now the highest-leverage thing an engineer writes.