Code with PHP

Appearance

Deals Module - CRUD & Pipeline Interface

Chapter 16: Deals Module - CRUD & Pipeline Interface ​

Overview ​

Your pipeline is designed, your database is ready—now it's time to build the interface that turns your CRM into a revenue-tracking powerhouse. The Deals CRUD interface is where sales teams live: creating opportunities, updating amounts, transitioning deals through stages, and ultimately marking deals as Won or Lost.

In this chapter, you'll build a complete Deal management system with Create, Read, Update, and Delete operations plus a visual Kanban-style pipeline board. You'll implement drag-and-drop functionality (or select-based stage transitions), create Laravel controllers with authorization ensuring team data isolation, build React/Inertia views displaying deals grouped by stage, and demonstrate real-world patterns like weighted forecasting and stage history tracking.

By the end of this chapter, your sales team will be able to:

  • View the sales pipeline in a visual Kanban board with deals organized by stage
  • Create new deals linked to companies and contacts with expected closing dates
  • Drag deals between stages (or use dropdown selection) triggering automatic history tracking
  • View deal details showing complete information, related contacts, and stage history
  • Edit deal information including amount, closing date, and assigned owner
  • Delete deals with soft delete support for recovery
  • Track weighted forecasts showing realistic revenue projections based on stage probability

This chapter combines everything you've learned: controllers, policies, eager loading, complex forms, and advanced React UI patterns. You're building the centerpiece of a professional CRM system.

Prerequisites ​

Before starting this chapter, you should have:

  • ✅ Completed Chapter 15 with Deal model and pipeline stages configured
  • ✅ Completed Chapter 14 to understand CRUD patterns
  • ✅ Completed Chapter 09 to understand authorization policies
  • ✅ Laravel Sail running with all containers active
  • ✅ Database migrations applied with deals, pipeline_stages, and relationships populated
  • ✅ Basic understanding of Laravel controllers, policies, Inertia.js, and React hooks
  • ✅ Familiarity with React drag-and-drop libraries (we'll use dnd-kit) or select-based alternatives

Estimated Time: ~140 minutes (includes controllers, policies, routes, Kanban board UI, drag-and-drop, deal forms, and stage history tracking)

Verify your setup:

bash
# Navigate to your project
cd crm-app

# Verify Sail is running
sail ps  # Should show: laravel.test, mysql, redis all "Up"

# Verify Deal model and relationships work
sail artisan tinker
$deal = App\Models\Deal::first();
echo $deal->title;
echo $deal->company->name;
echo $deal->stage->name;
$deal->stageHistory()->count();  # Should work
exit

What You'll Build ​

By the end of this chapter, you will have:

Backend Controllers & Security:

  • ✅ DealController with resourceful CRUD methods plus updateStage() for transitions
  • ✅ DealRequest FormRequest validating deal data with team-specific rules
  • ✅ DealPolicy authorizing all actions at the team level
  • ✅ PipelineController serving Kanban board data with deals grouped by stage
  • ✅ Stage transition logic creating immutable history records on every move
  • ✅ Weighted forecast calculations showing realistic revenue projections
  • ✅ Team-scoped queries ensuring users only see their team's deals

Frontend Views (React/Inertia):

  • ✅ Pipeline Kanban Board displaying deals in columns by stage
  • ✅ Drag-and-drop support using @dnd-kit/core for smooth transitions
  • ✅ Deal cards showing title, company, amount, closing date, and owner
  • ✅ Deals Index with list view, filters, and search
  • ✅ Deal Show displaying complete details with stage history timeline
  • ✅ Deal Create/Edit form linking to companies and contacts
  • ✅ Stage history component showing who moved the deal when and why

Integration:

  • ✅ Resourceful routes for deals using Route::resource()
  • ✅ Custom route for stage updates: PATCH /deals/{deal}/stage
  • ✅ Authorization checks on every action ensuring team isolation
  • ✅ Eager loading preventing N+1 queries when loading deals with relationships
  • ✅ Real-time UI updates (optimistic updates for smooth UX)
  • ✅ Complete working deals management ready for Chapter 17

Quick Start ​

Want to see it working in 5 minutes? Here's the end result:

bash
# After completing this chapter:

# 1. View the pipeline board
open http://localhost/pipeline

# 2. Create a new deal
# Click "New Deal" → Fill form → Save
# Expected: Deal appears in "New" column

# 3. Drag deal to "In Progress"
# Drag card from "New" to "In Progress" column
# Expected: Card moves, history record created

# 4. View deal details
open http://localhost/deals/1
# Expected: Full details, stage history timeline

# 5. Check weighted forecast
# Pipeline board shows: Total value, weighted forecast by stage
# Expected: Accurate revenue projections

Objectives ​

By completing this chapter, you will:

  • Build a DealController with full CRUD operations and stage update endpoint
  • Create a Deal policy enforcing team-based authorization on all actions
  • Implement FormRequest validation with custom rules for deal data
  • Design a Kanban pipeline board in React displaying deals grouped by stage
  • Add drag-and-drop functionality using @dnd-kit/core for smooth interactions
  • Track stage transitions creating immutable history records automatically
  • Calculate weighted forecasts showing realistic revenue based on stage probability
  • Master relational forms linking deals to companies, contacts, and users

Step 1: Generate Deal Controller and Policy (~15 min) ​

Goal ​

Create the Laravel controller handling all deal operations and the policy enforcing team-level authorization.

Actions ​

  1. Generate controller and policy:
bash
# Generate resourceful controller
sail artisan make:controller DealController --resource

# Generate policy
sail artisan make:policy DealPolicy --model=Deal
  1. Build DealController (app/Http/Controllers/DealController.php):
php
<?php

namespace App\Http\Controllers;

use App\Models\Deal;
use App\Models\Company;
use App\Models\Contact;
use App\Models\PipelineStage;
use App\Models\User;
use App\Http\Requests\DealRequest;
use Illuminate\Http\Request;
use Inertia\Inertia;

class DealController extends Controller
{
    public function __construct()
    {
        $this->authorizeResource(Deal::class, 'deal');
    }

    public function index(Request $request)
    {
        $query = Deal::query()
            ->with(['company', 'stage', 'owner', 'primaryContact'])
            ->where('team_id', $request->user()->currentTeam->id);

        // Search
        if ($search = $request->input('search')) {
            $query->where(function ($q) use ($search) {
                $q->where('title', 'like', "%{$search}%")
                  ->orWhereHas('company', fn($q) => $q->where('name', 'like', "%{$search}%"));
            });
        }

        // Filter by stage
        if ($stageId = $request->input('stage_id')) {
            $query->where('pipeline_stage_id', $stageId);
        }

        // Filter by owner
        if ($ownerId = $request->input('owner_id')) {
            $query->where('owner_id', $ownerId);
        }

        // Sort
        $sortField = $request->input('sort', 'created_at');
        $sortDirection = $request->input('direction', 'desc');
        $query->orderBy($sortField, $sortDirection);

        $deals = $query->paginate(25)->withQueryString();

        return Inertia::render('Deals/Index', [
            'deals' => $deals,
            'filters' => $request->only(['search', 'stage_id', 'owner_id', 'sort', 'direction']),
            'stages' => PipelineStage::all(),
            'users' => User::where('current_team_id', $request->user()->currentTeam->id)->get(),
        ]);
    }

    public function create()
    {
        return Inertia::render('Deals/Create', [
            'companies' => Company::where('team_id', auth()->user()->currentTeam->id)
                ->orderBy('name')
                ->get(['id', 'name']),
            'contacts' => Contact::where('team_id', auth()->user()->currentTeam->id)
                ->orderBy('first_name')
                ->get(['id', 'first_name', 'last_name']),
            'stages' => PipelineStage::all(),
            'users' => User::where('current_team_id', auth()->user()->currentTeam->id)
                ->get(['id', 'name']),
        ]);
    }

    public function store(DealRequest $request)
    {
        $deal = Deal::create([
            ...$request->validated(),
            'team_id' => $request->user()->currentTeam->id,
            'owner_id' => $request->input('owner_id', $request->user()->id),
        ]);

        // Create initial stage history
        $deal->stageHistory()->create([
            'pipeline_stage_id' => $deal->pipeline_stage_id,
            'user_id' => $request->user()->id,
            'notes' => 'Deal created',
        ]);

        return redirect()
            ->route('deals.show', $deal)
            ->with('success', 'Deal created successfully.');
    }

    public function show(Deal $deal)
    {
        $deal->load([
            'company',
            'primaryContact',
            'stage',
            'owner',
            'stageHistory.user',
            'stageHistory.stage',
        ]);

        return Inertia::render('Deals/Show', [
            'deal' => $deal,
        ]);
    }

    public function edit(Deal $deal)
    {
        return Inertia::render('Deals/Edit', [
            'deal' => $deal->load('company', 'primaryContact', 'stage', 'owner'),
            'companies' => Company::where('team_id', auth()->user()->currentTeam->id)
                ->orderBy('name')
                ->get(['id', 'name']),
            'contacts' => Contact::where('team_id', auth()->user()->currentTeam->id)
                ->orderBy('first_name')
                ->get(['id', 'first_name', 'last_name']),
            'stages' => PipelineStage::all(),
            'users' => User::where('current_team_id', auth()->user()->currentTeam->id)
                ->get(['id', 'name']),
        ]);
    }

    public function update(DealRequest $request, Deal $deal)
    {
        $deal->update($request->validated());

        return redirect()
            ->route('deals.show', $deal)
            ->with('success', 'Deal updated successfully.');
    }

    public function destroy(Deal $deal)
    {
        $deal->delete();

        return redirect()
            ->route('deals.index')
            ->with('success', 'Deal deleted successfully.');
    }

    public function updateStage(Request $request, Deal $deal)
    {
        $this->authorize('update', $deal);

        $validated = $request->validate([
            'pipeline_stage_id' => 'required|exists:pipeline_stages,id',
            'notes' => 'nullable|string|max:500',
        ]);

        $oldStageId = $deal->pipeline_stage_id;

        $deal->update([
            'pipeline_stage_id' => $validated['pipeline_stage_id'],
        ]);

        // Record stage history
        $deal->stageHistory()->create([
            'pipeline_stage_id' => $validated['pipeline_stage_id'],
            'user_id' => $request->user()->id,
            'notes' => $validated['notes'] ?? "Moved from {$oldStageId} to {$validated['pipeline_stage_id']}",
        ]);

        return back()->with('success', 'Deal stage updated.');
    }
}
  1. Build DealPolicy (app/Policies/DealPolicy.php):
php
<?php

namespace App\Policies;

use App\Models\Deal;
use App\Models\User;

class DealPolicy
{
    public function viewAny(User $user): bool
    {
        return true; // All authenticated users can view their team's deals
    }

    public function view(User $user, Deal $deal): bool
    {
        return $user->currentTeam->id === $deal->team_id;
    }

    public function create(User $user): bool
    {
        return true; // All team members can create deals
    }

    public function update(User $user, Deal $deal): bool
    {
        return $user->currentTeam->id === $deal->team_id;
    }

    public function delete(User $user, Deal $deal): bool
    {
        return $user->currentTeam->id === $deal->team_id;
    }

    public function restore(User $user, Deal $deal): bool
    {
        return $user->currentTeam->id === $deal->team_id;
    }

    public function forceDelete(User $user, Deal $deal): bool
    {
        return $user->currentTeam->id === $deal->team_id;
    }
}
  1. Create DealRequest for validation:
bash
sail artisan make:request DealRequest

Build DealRequest (app/Http/Requests/DealRequest.php):

php
<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class DealRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true; // Policy handles authorization
    }

    public function rules(): array
    {
        $dealId = $this->route('deal')?->id;

        return [
            'title' => [
                'required',
                'string',
                'max:255',
                'unique:deals,title,' . $dealId . ',id,team_id,' . $this->user()->currentTeam->id,
            ],
            'description' => 'nullable|string',
            'amount' => 'required|numeric|min:0|max:999999999.99',
            'company_id' => 'required|exists:companies,id',
            'primary_contact_id' => 'nullable|exists:contacts,id',
            'pipeline_stage_id' => 'required|exists:pipeline_stages,id',
            'expected_close_date' => 'nullable|date|after_or_equal:today',
            'owner_id' => 'nullable|exists:users,id',
        ];
    }

    public function messages(): array
    {
        return [
            'title.unique' => 'A deal with this title already exists in your team.',
            'amount.required' => 'Please enter the deal amount.',
            'company_id.required' => 'Please select a company for this deal.',
            'expected_close_date.after_or_equal' => 'The closing date must be today or in the future.',
        ];
    }
}

Expected Result ​

bash
# Test policy and controller
sail artisan tinker
$user = User::first();
$deal = Deal::first();
Gate::authorize('view', $deal);  # Should pass if same team
# Expected: No exception

Why It Works ​

The DealController follows Laravel's resourceful pattern with automatic route model binding and policy authorization via authorizeResource(). The custom updateStage() method handles stage transitions separately from full updates, allowing drag-and-drop operations without requiring all deal fields.

The DealPolicy enforces team-level isolation on every action, ensuring users can only interact with their team's deals. The DealRequest validates all input with team-scoped uniqueness rules preventing duplicate deal titles within the same team.

The controller uses eager loading (with()) to prevent N+1 queries when loading deals with relationships, improving performance significantly when displaying lists of deals.

Troubleshooting ​

  • Error: "Call to undefined method authorizeResource()" — Ensure the controller extends App\Http\Controllers\Controller base class
  • Policy not enforced — Run sail artisan optimize:clear to clear cached policies
  • Unique validation fails — Verify team_id column exists on deals table and matches current team

Step 2: Create Pipeline Board Controller (~10 min) ​

Goal ​

Build a dedicated controller serving the Kanban board with deals grouped by stage.

Actions ​

  1. Generate controller:
bash
sail artisan make:controller PipelineController
  1. Build PipelineController (app/Http/Controllers/PipelineController.php):
php
<?php

namespace App\Http\Controllers;

use App\Models\Deal;
use App\Models\PipelineStage;
use Illuminate\Http\Request;
use Inertia\Inertia;

class PipelineController extends Controller
{
    public function index(Request $request)
    {
        $teamId = $request->user()->currentTeam->id;

        // Get all stages with deals
        $stages = PipelineStage::with([
            'deals' => function ($query) use ($teamId) {
                $query->where('team_id', $teamId)
                    ->with(['company', 'owner', 'primaryContact'])
                    ->orderBy('expected_close_date');
            }
        ])->orderBy('order')->get();

        // Calculate metrics
        $totalValue = Deal::where('team_id', $teamId)->sum('amount');
        $weightedForecast = Deal::where('team_id', $teamId)
            ->join('pipeline_stages', 'deals.pipeline_stage_id', '=', 'pipeline_stages.id')
            ->selectRaw('SUM(deals.amount * pipeline_stages.probability / 100) as forecast')
            ->value('forecast');

        $dealCountByStage = Deal::where('team_id', $teamId)
            ->selectRaw('pipeline_stage_id, COUNT(*) as count')
            ->groupBy('pipeline_stage_id')
            ->pluck('count', 'pipeline_stage_id');

        return Inertia::render('Pipeline/Index', [
            'stages' => $stages,
            'metrics' => [
                'total_value' => $totalValue,
                'weighted_forecast' => round($weightedForecast, 2),
                'deal_count' => Deal::where('team_id', $teamId)->count(),
                'deal_count_by_stage' => $dealCountByStage,
            ],
        ]);
    }

    public function updateStage(Request $request, Deal $deal)
    {
        $this->authorize('update', $deal);

        $validated = $request->validate([
            'pipeline_stage_id' => 'required|exists:pipeline_stages,id',
        ]);

        $oldStage = $deal->stage;
        $newStage = PipelineStage::findOrFail($validated['pipeline_stage_id']);

        $deal->update([
            'pipeline_stage_id' => $newStage->id,
        ]);

        // Create history record
        $deal->stageHistory()->create([
            'pipeline_stage_id' => $newStage->id,
            'user_id' => $request->user()->id,
            'notes' => "Moved from {$oldStage->name} to {$newStage->name}",
        ]);

        return response()->json([
            'message' => 'Deal stage updated successfully',
            'deal' => $deal->load(['company', 'owner', 'stage']),
        ]);
    }
}

Expected Result ​

bash
# Test the pipeline endpoint
sail artisan tinker
$response = app()->make('App\Http\Controllers\PipelineController')->index(request());
# Expected: Inertia response with stages and metrics

Why It Works ​

The PipelineController loads all stages with their associated deals in a single query using eager loading. The deals relationship is constrained to the current team and ordered by expected close date, ensuring efficient data loading.

The metrics calculation uses SQL aggregation to compute total deal value and weighted forecast without loading all deals into memory. The weighted forecast multiplies each deal amount by its stage probability, giving a realistic revenue projection.

The updateStage method returns JSON instead of redirecting, making it perfect for AJAX requests from the drag-and-drop interface where we want to update the UI without a full page reload.

Troubleshooting ​

  • N+1 query detected — Verify with(['company', 'owner', 'primaryContact']) is present in the deals query
  • Weighted forecast is null — Ensure pipeline_stages table has probability column with numeric values
  • Authorization fails — Add Gate::allows('viewAny', Deal::class) check before loading data

Step 3: Register Routes (~5 min) ​

Goal ​

Define routes for deals and pipeline board.

Actions ​

  1. Add routes to routes/web.php:
php
use App\Http\Controllers\DealController;
use App\Http\Controllers\PipelineController;

// Deals resource routes
Route::middleware(['auth', 'verified'])->group(function () {
    // Pipeline board
    Route::get('/pipeline', [PipelineController::class, 'index'])->name('pipeline.index');
    Route::patch('/deals/{deal}/stage', [PipelineController::class, 'updateStage'])->name('deals.update-stage');

    // Deals CRUD
    Route::resource('deals', DealController::class);
});
  1. Test routes:
bash
# List all deal routes
sail artisan route:list --name=deals

# Expected output:
# GET    /deals ...................... deals.index
# POST   /deals ...................... deals.store
# GET    /deals/create ............... deals.create
# GET    /deals/{deal} ............... deals.show
# PUT    /deals/{deal} ............... deals.update
# DELETE /deals/{deal} ............... deals.destroy
# GET    /deals/{deal}/edit .......... deals.edit
# PATCH  /deals/{deal}/stage ......... deals.update-stage
# GET    /pipeline ................... pipeline.index

Expected Result ​

bash
# Verify routes work
open http://localhost/pipeline
# Expected: Pipeline board loads (after creating views)

Why It Works ​

Resourceful routes via Route::resource() automatically generate all seven CRUD routes with correct HTTP methods and route names. The custom updateStage route is added separately with a PATCH method, allowing stage updates without requiring all deal fields.

Route names like deals.index and pipeline.index are used throughout the application for URL generation via route() helper, making the code maintainable and refactoring-safe.

Troubleshooting ​

  • Route not found — Run sail artisan route:clear and verify route names
  • Middleware not applied — Ensure routes are within middleware(['auth', 'verified']) group
  • PATCH method not working — Verify forms include @method('PATCH') directive

Step 4: Build Deals Index View (~20 min) ​

Goal ​

Create a React/Inertia view listing all deals with search, filters, and sorting.

Actions ​

  1. Create Deals Index (resources/js/Pages/Deals/Index.tsx):
tsx
import React, { useState } from "react";
import { Head, Link, router } from "@inertiajs/react";
import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
import { Button } from "@/Components/ui/button";
import { Input } from "@/Components/ui/input";
import { Select } from "@/Components/ui/select";
import { Badge } from "@/Components/ui/badge";
import { formatCurrency, formatDate } from "@/lib/utils";

interface Deal {
  id: number;
  title: string;
  amount: number;
  expected_close_date: string | null;
  company: { id: number; name: string };
  stage: { id: number; name: string; color: string };
  owner: { id: number; name: string } | null;
  primary_contact: { id: number; first_name: string; last_name: string } | null;
}

interface Props {
  deals: {
    data: Deal[];
    links: any[];
    meta: any;
  };
  filters: {
    search?: string;
    stage_id?: number;
    owner_id?: number;
    sort?: string;
    direction?: string;
  };
  stages: Array<{ id: number; name: string }>;
  users: Array<{ id: number; name: string }>;
}

export default function Index({ deals, filters, stages, users }: Props) {
  const [search, setSearch] = useState(filters.search || "");

  const handleFilter = (key: string, value: string) => {
    router.get(
      route("deals.index"),
      {
        ...filters,
        [key]: value,
      },
      {
        preserveState: true,
        replace: true,
      }
    );
  };

  const handleSort = (field: string) => {
    const direction =
      filters.sort === field && filters.direction === "asc" ? "desc" : "asc";
    router.get(
      route("deals.index"),
      {
        ...filters,
        sort: field,
        direction,
      },
      {
        preserveState: true,
        replace: true,
      }
    );
  };

  return (
    <AuthenticatedLayout
      header={
        <div className="flex justify-between items-center">
          <h2 className="font-semibold text-xl text-gray-800 leading-tight">
            Deals
          </h2>
          <div className="flex gap-2">
            <Link href={route("pipeline.index")}>
              <Button variant="outline">Pipeline Board</Button>
            </Link>
            <Link href={route("deals.create")}>
              <Button>New Deal</Button>
            </Link>
          </div>
        </div>
      }
    >
      <Head title="Deals" />

      <div className="py-12">
        <div className="max-w-7xl mx-auto sm:px-6 lg:px-8">
          {/* Filters */}
          <div className="bg-white shadow-sm rounded-lg p-6 mb-6">
            <div className="grid grid-cols-1 md:grid-cols-4 gap-4">
              <Input
                placeholder="Search deals..."
                value={search}
                onChange={(e) => setSearch(e.target.value)}
                onKeyUp={(e) =>
                  e.key === "Enter" && handleFilter("search", search)
                }
              />
              <Select
                value={filters.stage_id?.toString()}
                onValueChange={(value) => handleFilter("stage_id", value)}
              >
                <option value="">All Stages</option>
                {stages.map((stage) => (
                  <option key={stage.id} value={stage.id}>
                    {stage.name}
                  </option>
                ))}
              </Select>
              <Select
                value={filters.owner_id?.toString()}
                onValueChange={(value) => handleFilter("owner_id", value)}
              >
                <option value="">All Owners</option>
                {users.map((user) => (
                  <option key={user.id} value={user.id}>
                    {user.name}
                  </option>
                ))}
              </Select>
              <Button
                variant="outline"
                onClick={() => router.get(route("deals.index"))}
              >
                Clear Filters
              </Button>
            </div>
          </div>

          {/* Deals Table */}
          <div className="bg-white shadow-sm rounded-lg overflow-hidden">
            <table className="min-w-full divide-y divide-gray-200">
              <thead className="bg-gray-50">
                <tr>
                  <th
                    className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider cursor-pointer"
                    onClick={() => handleSort("title")}
                  >
                    Title
                  </th>
                  <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">
                    Company
                  </th>
                  <th
                    className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider cursor-pointer"
                    onClick={() => handleSort("amount")}
                  >
                    Amount
                  </th>
                  <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">
                    Stage
                  </th>
                  <th
                    className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider cursor-pointer"
                    onClick={() => handleSort("expected_close_date")}
                  >
                    Close Date
                  </th>
                  <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">
                    Owner
                  </th>
                  <th className="px-6 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">
                    Actions
                  </th>
                </tr>
              </thead>
              <tbody className="bg-white divide-y divide-gray-200">
                {deals.data.map((deal) => (
                  <tr key={deal.id} className="hover:bg-gray-50">
                    <td className="px-6 py-4 whitespace-nowrap">
                      <Link
                        href={route("deals.show", deal.id)}
                        className="text-blue-600 hover:text-blue-900 font-medium"
                      >
                        {deal.title}
                      </Link>
                    </td>
                    <td className="px-6 py-4 whitespace-nowrap">
                      <Link
                        href={route("companies.show", deal.company.id)}
                        className="text-gray-600 hover:text-gray-900"
                      >
                        {deal.company.name}
                      </Link>
                    </td>
                    <td className="px-6 py-4 whitespace-nowrap font-semibold">
                      {formatCurrency(deal.amount)}
                    </td>
                    <td className="px-6 py-4 whitespace-nowrap">
                      <Badge style={{ backgroundColor: deal.stage.color }}>
                        {deal.stage.name}
                      </Badge>
                    </td>
                    <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-600">
                      {deal.expected_close_date
                        ? formatDate(deal.expected_close_date)
                        : "Not set"}
                    </td>
                    <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-600">
                      {deal.owner?.name || "Unassigned"}
                    </td>
                    <td className="px-6 py-4 whitespace-nowrap text-right text-sm font-medium">
                      <Link
                        href={route("deals.edit", deal.id)}
                        className="text-indigo-600 hover:text-indigo-900 mr-3"
                      >
                        Edit
                      </Link>
                    </td>
                  </tr>
                ))}
              </tbody>
            </table>

            {/* Pagination */}
            <div className="px-6 py-4 border-t">
              {/* Add pagination component here */}
            </div>
          </div>
        </div>
      </div>
    </AuthenticatedLayout>
  );
}
  1. Add utility functions (resources/js/lib/utils.ts):
typescript
export function formatCurrency(amount: number): string {
  return new Intl.NumberFormat("en-US", {
    style: "currency",
    currency: "USD",
  }).format(amount);
}

export function formatDate(date: string): string {
  return new Date(date).toLocaleDateString("en-US", {
    year: "numeric",
    month: "short",
    day: "numeric",
  });
}

Expected Result ​

bash
# Visit deals index
open http://localhost/deals

# Expected:
# - Table listing all deals
# - Search bar filtering by title/company
# - Dropdowns filtering by stage/owner
# - Sortable columns
# - Links to pipeline board and create deal

Why It Works ​

The Deals Index uses Inertia's router.get() for client-side navigation with preserveState: true, keeping filter values in the URL as query parameters. This makes filters bookmarkable and allows users to share filtered views.

Sorting toggles between ascending and descending by checking if the current sort field matches the clicked column. The UI shows visual feedback via cursor-pointer on sortable headers.

Links use Inertia's <Link> component for instant navigation without full page reloads, providing a SPA-like experience while maintaining server-side rendering benefits.

Troubleshooting ​

  • TypeScript errors — Install types: npm install @types/react --save-dev
  • Badge component missing — Install shadcn/ui badge: npx shadcn-ui@latest add badge
  • formatCurrency undefined — Verify utils.ts file exists and exports functions

Step 5: Build Pipeline Kanban Board (~30 min) ​

Goal ​

Create a visual Kanban board displaying deals grouped by stage with drag-and-drop support.

Actions ​

  1. Install drag-and-drop library:
bash
# Using dnd-kit (modern, accessible drag-and-drop)
npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
  1. Create Pipeline Board (resources/js/Pages/Pipeline/Index.tsx):
tsx
import React, { useState } from "react";
import { Head, Link, router } from "@inertiajs/react";
import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
import { Button } from "@/Components/ui/button";
import { Card } from "@/Components/ui/card";
import { Badge } from "@/Components/ui/badge";
import { formatCurrency, formatDate } from "@/lib/utils";
import {
  DndContext,
  DragEndEvent,
  DragOverlay,
  DragStartEvent,
  PointerSensor,
  useSensor,
  useSensors,
} from "@dnd-kit/core";

interface Deal {
  id: number;
  title: string;
  amount: number;
  expected_close_date: string | null;
  company: { id: number; name: string };
  owner: { id: number; name: string } | null;
  primary_contact: { id: number; first_name: string; last_name: string } | null;
}

interface Stage {
  id: number;
  name: string;
  color: string;
  probability: number;
  order: number;
  deals: Deal[];
}

interface Props {
  stages: Stage[];
  metrics: {
    total_value: number;
    weighted_forecast: number;
    deal_count: number;
    deal_count_by_stage: Record<number, number>;
  };
}

export default function PipelineIndex({ stages, metrics }: Props) {
  const [activeDeal, setActiveDeal] = useState<Deal | null>(null);

  const sensors = useSensors(
    useSensor(PointerSensor, {
      activationConstraint: {
        distance: 8, // Require 8px movement before drag starts
      },
    })
  );

  const handleDragStart = (event: DragStartEvent) => {
    const dealId = event.active.id as number;
    const deal = stages
      .flatMap((stage) => stage.deals)
      .find((d) => d.id === dealId);
    setActiveDeal(deal || null);
  };

  const handleDragEnd = (event: DragEndEvent) => {
    const { active, over } = event;

    if (!over) {
      setActiveDeal(null);
      return;
    }

    const dealId = active.id as number;
    const newStageId = parseInt(over.id as string);

    // Find current stage
    const currentStage = stages.find((stage) =>
      stage.deals.some((deal) => deal.id === dealId)
    );

    if (!currentStage || currentStage.id === newStageId) {
      setActiveDeal(null);
      return;
    }

    // Update stage via API
    router.patch(
      route("deals.update-stage", dealId),
      { pipeline_stage_id: newStageId },
      {
        preserveState: true,
        onSuccess: () => {
          // Reload to get updated metrics
          router.reload({ only: ["stages", "metrics"] });
        },
      }
    );

    setActiveDeal(null);
  };

  return (
    <AuthenticatedLayout
      header={
        <div className="flex justify-between items-center">
          <h2 className="font-semibold text-xl text-gray-800 leading-tight">
            Sales Pipeline
          </h2>
          <div className="flex gap-2">
            <Link href={route("deals.index")}>
              <Button variant="outline">List View</Button>
            </Link>
            <Link href={route("deals.create")}>
              <Button>New Deal</Button>
            </Link>
          </div>
        </div>
      }
    >
      <Head title="Sales Pipeline" />

      <div className="py-12">
        <div className="max-w-7xl mx-auto sm:px-6 lg:px-8">
          {/* Metrics */}
          <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-6">
            <Card className="p-6">
              <div className="text-sm text-gray-600">Total Pipeline Value</div>
              <div className="text-3xl font-bold text-gray-900 mt-2">
                {formatCurrency(metrics.total_value)}
              </div>
              <div className="text-sm text-gray-500 mt-1">
                {metrics.deal_count} deals
              </div>
            </Card>
            <Card className="p-6">
              <div className="text-sm text-gray-600">Weighted Forecast</div>
              <div className="text-3xl font-bold text-green-600 mt-2">
                {formatCurrency(metrics.weighted_forecast)}
              </div>
              <div className="text-sm text-gray-500 mt-1">
                Based on stage probability
              </div>
            </Card>
            <Card className="p-6">
              <div className="text-sm text-gray-600">Win Rate</div>
              <div className="text-3xl font-bold text-blue-600 mt-2">
                {(
                  (metrics.weighted_forecast / metrics.total_value) *
                  100
                ).toFixed(1)}
                %
              </div>
              <div className="text-sm text-gray-500 mt-1">
                Probability-weighted
              </div>
            </Card>
          </div>

          {/* Kanban Board */}
          <DndContext
            sensors={sensors}
            onDragStart={handleDragStart}
            onDragEnd={handleDragEnd}
          >
            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
              {stages.map((stage) => (
                <StageColumn key={stage.id} stage={stage} metrics={metrics} />
              ))}
            </div>

            <DragOverlay>
              {activeDeal && <DealCard deal={activeDeal} isDragging />}
            </DragOverlay>
          </DndContext>
        </div>
      </div>
    </AuthenticatedLayout>
  );
}

// Stage Column Component
function StageColumn({ stage, metrics }: { stage: Stage; metrics: any }) {
  const { useDroppable } = require("@dnd-kit/core");
  const { setNodeRef } = useDroppable({ id: stage.id });

  const stageValue = stage.deals.reduce((sum, deal) => sum + deal.amount, 0);
  const dealCount = metrics.deal_count_by_stage[stage.id] || 0;

  return (
    <div ref={setNodeRef} className="bg-gray-100 rounded-lg p-4 min-h-[600px]">
      {/* Stage Header */}
      <div className="mb-4">
        <div className="flex items-center justify-between mb-2">
          <h3 className="font-semibold text-gray-900">{stage.name}</h3>
          <Badge style={{ backgroundColor: stage.color }}>{dealCount}</Badge>
        </div>
        <div className="text-sm text-gray-600">
          {formatCurrency(stageValue)}
        </div>
        <div className="text-xs text-gray-500">
          {stage.probability}% probability
        </div>
      </div>

      {/* Deals */}
      <div className="space-y-3">
        {stage.deals.map((deal) => (
          <DealCard key={deal.id} deal={deal} />
        ))}
      </div>
    </div>
  );
}

// Deal Card Component
function DealCard({
  deal,
  isDragging = false,
}: {
  deal: Deal;
  isDragging?: boolean;
}) {
  const { useDraggable } = require("@dnd-kit/core");
  const { attributes, listeners, setNodeRef, transform } = useDraggable({
    id: deal.id,
  });

  const style = transform
    ? {
        transform: `translate3d(${transform.x}px, ${transform.y}px, 0)`,
      }
    : undefined;

  return (
    <Card
      ref={setNodeRef}
      style={style}
      {...listeners}
      {...attributes}
      className={`p-4 cursor-move hover:shadow-md transition-shadow ${
        isDragging ? "opacity-50" : ""
      }`}
    >
      <Link href={route("deals.show", deal.id)} className="block">
        <h4 className="font-semibold text-gray-900 mb-2 hover:text-blue-600">
          {deal.title}
        </h4>
        <div className="text-sm text-gray-600 mb-2">{deal.company.name}</div>
        <div className="text-lg font-bold text-green-600 mb-2">
          {formatCurrency(deal.amount)}
        </div>
        {deal.expected_close_date && (
          <div className="text-xs text-gray-500">
            Close: {formatDate(deal.expected_close_date)}
          </div>
        )}
        {deal.owner && (
          <div className="text-xs text-gray-500 mt-1">
            Owner: {deal.owner.name}
          </div>
        )}
      </Link>
    </Card>
  );
}
  1. Build assets:
bash
npm run build

Expected Result ​

bash
# Visit pipeline board
open http://localhost/pipeline

# Expected:
# - 4 columns (New, In Progress, Won, Lost)
# - Deal cards in each column
# - Drag cards between columns
# - Metrics at top showing total value and forecast
# - Cards link to deal details

Why It Works ​

@dnd-kit provides accessible, performant drag-and-drop with keyboard support. The DndContext wraps the entire board, useDroppable makes columns accept drops, and useDraggable makes cards draggable.

When a deal is dropped, handleDragEnd sends a PATCH request to deals.update-stage, updating the database and creating a history record. The router.reload() fetches fresh data, ensuring the UI stays in sync.

Optimistic updates could be added by immediately moving the card in state before the API call, then rolling back on error. This makes the UI feel instant while maintaining data integrity.

Troubleshooting ​

  • Cards not dragging — Verify cursor-move class is present and listeners props are spread correctly
  • Drop not working — Ensure setNodeRef is attached to the column container
  • TypeScript errors — Run npm install @types/react @types/react-dom --save-dev

Step 6: Create Deal Form Views (~25 min) ​

Goal ​

Build Create and Edit forms for deals with company/contact selection.

Actions ​

  1. Create Deal Create Form (resources/js/Pages/Deals/Create.tsx):
tsx
import React from "react";
import { Head, Link, useForm } from "@inertiajs/react";
import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
import { Button } from "@/Components/ui/button";
import { Input } from "@/Components/ui/input";
import { Label } from "@/Components/ui/label";
import { Select } from "@/Components/ui/select";
import { Textarea } from "@/Components/ui/textarea";

interface Props {
  companies: Array<{ id: number; name: string }>;
  contacts: Array<{ id: number; first_name: string; last_name: string }>;
  stages: Array<{ id: number; name: string }>;
  users: Array<{ id: number; name: string }>;
}

export default function Create({ companies, contacts, stages, users }: Props) {
  const { data, setData, post, processing, errors } = useForm({
    title: "",
    description: "",
    amount: "",
    company_id: "",
    primary_contact_id: "",
    pipeline_stage_id: stages[0]?.id.toString() || "",
    expected_close_date: "",
    owner_id: "",
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    post(route("deals.store"));
  };

  return (
    <AuthenticatedLayout
      header={
        <h2 className="font-semibold text-xl text-gray-800 leading-tight">
          Create New Deal
        </h2>
      }
    >
      <Head title="Create Deal" />

      <div className="py-12">
        <div className="max-w-3xl mx-auto sm:px-6 lg:px-8">
          <div className="bg-white shadow-sm rounded-lg p-6">
            <form onSubmit={handleSubmit} className="space-y-6">
              {/* Title */}
              <div>
                <Label htmlFor="title">Deal Title *</Label>
                <Input
                  id="title"
                  value={data.title}
                  onChange={(e) => setData("title", e.target.value)}
                  placeholder="e.g., Enterprise Software License"
                  className={errors.title ? "border-red-500" : ""}
                />
                {errors.title && (
                  <p className="text-sm text-red-600 mt-1">{errors.title}</p>
                )}
              </div>

              {/* Description */}
              <div>
                <Label htmlFor="description">Description</Label>
                <Textarea
                  id="description"
                  value={data.description}
                  onChange={(e) => setData("description", e.target.value)}
                  placeholder="Deal details and notes..."
                  rows={4}
                />
              </div>

              {/* Amount */}
              <div>
                <Label htmlFor="amount">Deal Amount *</Label>
                <Input
                  id="amount"
                  type="number"
                  step="0.01"
                  value={data.amount}
                  onChange={(e) => setData("amount", e.target.value)}
                  placeholder="0.00"
                  className={errors.amount ? "border-red-500" : ""}
                />
                {errors.amount && (
                  <p className="text-sm text-red-600 mt-1">{errors.amount}</p>
                )}
              </div>

              {/* Company */}
              <div>
                <Label htmlFor="company_id">Company *</Label>
                <Select
                  id="company_id"
                  value={data.company_id}
                  onValueChange={(value) => setData("company_id", value)}
                  className={errors.company_id ? "border-red-500" : ""}
                >
                  <option value="">Select a company</option>
                  {companies.map((company) => (
                    <option key={company.id} value={company.id}>
                      {company.name}
                    </option>
                  ))}
                </Select>
                {errors.company_id && (
                  <p className="text-sm text-red-600 mt-1">
                    {errors.company_id}
                  </p>
                )}
              </div>

              {/* Primary Contact */}
              <div>
                <Label htmlFor="primary_contact_id">Primary Contact</Label>
                <Select
                  id="primary_contact_id"
                  value={data.primary_contact_id}
                  onValueChange={(value) =>
                    setData("primary_contact_id", value)
                  }
                >
                  <option value="">Select a contact (optional)</option>
                  {contacts.map((contact) => (
                    <option key={contact.id} value={contact.id}>
                      {contact.first_name} {contact.last_name}
                    </option>
                  ))}
                </Select>
              </div>

              {/* Stage */}
              <div>
                <Label htmlFor="pipeline_stage_id">Pipeline Stage *</Label>
                <Select
                  id="pipeline_stage_id"
                  value={data.pipeline_stage_id}
                  onValueChange={(value) => setData("pipeline_stage_id", value)}
                  className={errors.pipeline_stage_id ? "border-red-500" : ""}
                >
                  {stages.map((stage) => (
                    <option key={stage.id} value={stage.id}>
                      {stage.name}
                    </option>
                  ))}
                </Select>
                {errors.pipeline_stage_id && (
                  <p className="text-sm text-red-600 mt-1">
                    {errors.pipeline_stage_id}
                  </p>
                )}
              </div>

              {/* Expected Close Date */}
              <div>
                <Label htmlFor="expected_close_date">Expected Close Date</Label>
                <Input
                  id="expected_close_date"
                  type="date"
                  value={data.expected_close_date}
                  onChange={(e) =>
                    setData("expected_close_date", e.target.value)
                  }
                />
              </div>

              {/* Owner */}
              <div>
                <Label htmlFor="owner_id">Deal Owner</Label>
                <Select
                  id="owner_id"
                  value={data.owner_id}
                  onValueChange={(value) => setData("owner_id", value)}
                >
                  <option value="">Assign to a team member (optional)</option>
                  {users.map((user) => (
                    <option key={user.id} value={user.id}>
                      {user.name}
                    </option>
                  ))}
                </Select>
              </div>

              {/* Actions */}
              <div className="flex items-center justify-end gap-4">
                <Link href={route("deals.index")}>
                  <Button type="button" variant="outline">
                    Cancel
                  </Button>
                </Link>
                <Button type="submit" disabled={processing}>
                  {processing ? "Creating..." : "Create Deal"}
                </Button>
              </div>
            </form>
          </div>
        </div>
      </div>
    </AuthenticatedLayout>
  );
}
  1. Create Deal Edit Form (resources/js/Pages/Deals/Edit.tsx):

Same structure as Create.tsx, but use put() instead of post() and pre-populate form with deal data.

Expected Result ​

bash
# Visit create form
open http://localhost/deals/create

# Expected:
# - Form with all fields
# - Company dropdown populated
# - Stage dropdown with default "New"
# - Validation errors displayed
# - Submit creates deal and redirects

Why It Works ​

Inertia's useForm hook provides form state management, validation error handling, and submission with proper CSRF token handling. The processing state disables the submit button during submission, preventing double-clicks.

Select components are populated with data passed from the controller, ensuring users can only select valid companies, contacts, and stages from their team.

Troubleshooting ​

  • Form not submitting — Verify route('deals.store') matches route name in web.php
  • Validation errors not showing — Check errors object structure matches field names
  • Select dropdowns empty — Ensure controller passes companies, contacts, stages arrays

Step 7: Build Deal Show View with Stage History (~15 min) ​

Goal ​

Display complete deal details with a timeline of stage transitions.

Actions ​

  1. Create Deal Show View (resources/js/Pages/Deals/Show.tsx):
tsx
import React from "react";
import { Head, Link } from "@inertiajs/react";
import AuthenticatedLayout from "@/Layouts/AuthenticatedLayout";
import { Button } from "@/Components/ui/button";
import { Card } from "@/Components/ui/card";
import { Badge } from "@/Components/ui/badge";
import { formatCurrency, formatDate, formatDateTime } from "@/lib/utils";

interface Deal {
  id: number;
  title: string;
  description: string | null;
  amount: number;
  expected_close_date: string | null;
  company: { id: number; name: string };
  primary_contact: { id: number; first_name: string; last_name: string } | null;
  stage: { id: number; name: string; color: string; probability: number };
  owner: { id: number; name: string } | null;
  stage_history: Array<{
    id: number;
    stage: { id: number; name: string; color: string };
    user: { id: number; name: string };
    notes: string | null;
    created_at: string;
  }>;
  created_at: string;
  updated_at: string;
}

interface Props {
  deal: Deal;
}

export default function Show({ deal }: Props) {
  const weightedValue = (deal.amount * deal.stage.probability) / 100;

  return (
    <AuthenticatedLayout
      header={
        <div className="flex justify-between items-center">
          <h2 className="font-semibold text-xl text-gray-800 leading-tight">
            {deal.title}
          </h2>
          <div className="flex gap-2">
            <Link href={route("deals.edit", deal.id)}>
              <Button variant="outline">Edit</Button>
            </Link>
            <Link href={route("deals.index")}>
              <Button variant="outline">Back to List</Button>
            </Link>
          </div>
        </div>
      }
    >
      <Head title={deal.title} />

      <div className="py-12">
        <div className="max-w-7xl mx-auto sm:px-6 lg:px-8">
          <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
            {/* Main Details */}
            <div className="lg:col-span-2 space-y-6">
              {/* Deal Info Card */}
              <Card className="p-6">
                <h3 className="text-lg font-semibold mb-4">Deal Information</h3>
                <dl className="grid grid-cols-1 md:grid-cols-2 gap-4">
                  <div>
                    <dt className="text-sm font-medium text-gray-500">Title</dt>
                    <dd className="mt-1 text-sm text-gray-900">{deal.title}</dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">
                      Amount
                    </dt>
                    <dd className="mt-1 text-lg font-bold text-green-600">
                      {formatCurrency(deal.amount)}
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">
                      Company
                    </dt>
                    <dd className="mt-1 text-sm">
                      <Link
                        href={route("companies.show", deal.company.id)}
                        className="text-blue-600 hover:text-blue-900"
                      >
                        {deal.company.name}
                      </Link>
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">
                      Primary Contact
                    </dt>
                    <dd className="mt-1 text-sm">
                      {deal.primary_contact ? (
                        <Link
                          href={route("contacts.show", deal.primary_contact.id)}
                          className="text-blue-600 hover:text-blue-900"
                        >
                          {deal.primary_contact.first_name}{" "}
                          {deal.primary_contact.last_name}
                        </Link>
                      ) : (
                        <span className="text-gray-500">
                          No contact assigned
                        </span>
                      )}
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">Stage</dt>
                    <dd className="mt-1">
                      <Badge style={{ backgroundColor: deal.stage.color }}>
                        {deal.stage.name}
                      </Badge>
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">
                      Expected Close Date
                    </dt>
                    <dd className="mt-1 text-sm text-gray-900">
                      {deal.expected_close_date
                        ? formatDate(deal.expected_close_date)
                        : "Not set"}
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">Owner</dt>
                    <dd className="mt-1 text-sm text-gray-900">
                      {deal.owner?.name || "Unassigned"}
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">
                      Weighted Value
                    </dt>
                    <dd className="mt-1 text-sm font-semibold text-green-600">
                      {formatCurrency(weightedValue)}
                      <span className="text-gray-500 ml-1">
                        ({deal.stage.probability}%)
                      </span>
                    </dd>
                  </div>
                </dl>

                {deal.description && (
                  <div className="mt-6">
                    <dt className="text-sm font-medium text-gray-500 mb-2">
                      Description
                    </dt>
                    <dd className="text-sm text-gray-900 whitespace-pre-wrap">
                      {deal.description}
                    </dd>
                  </div>
                )}
              </Card>

              {/* Stage History */}
              <Card className="p-6">
                <h3 className="text-lg font-semibold mb-4">Stage History</h3>
                <div className="space-y-4">
                  {deal.stage_history.map((history, index) => (
                    <div key={history.id} className="flex gap-4">
                      <div className="flex-shrink-0">
                        <div
                          className="w-8 h-8 rounded-full flex items-center justify-center text-white text-sm font-semibold"
                          style={{ backgroundColor: history.stage.color }}
                        >
                          {index + 1}
                        </div>
                      </div>
                      <div className="flex-1 min-w-0">
                        <div className="flex items-center justify-between">
                          <p className="text-sm font-medium text-gray-900">
                            Moved to {history.stage.name}
                          </p>
                          <p className="text-sm text-gray-500">
                            {formatDateTime(history.created_at)}
                          </p>
                        </div>
                        <p className="text-sm text-gray-600">
                          By {history.user.name}
                        </p>
                        {history.notes && (
                          <p className="text-sm text-gray-700 mt-1">
                            {history.notes}
                          </p>
                        )}
                      </div>
                    </div>
                  ))}
                </div>
              </Card>
            </div>

            {/* Sidebar */}
            <div className="space-y-6">
              {/* Quick Stats */}
              <Card className="p-6">
                <h3 className="text-lg font-semibold mb-4">Quick Stats</h3>
                <dl className="space-y-3">
                  <div>
                    <dt className="text-sm text-gray-500">Created</dt>
                    <dd className="text-sm font-medium">
                      {formatDateTime(deal.created_at)}
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm text-gray-500">Last Updated</dt>
                    <dd className="text-sm font-medium">
                      {formatDateTime(deal.updated_at)}
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm text-gray-500">Days in Stage</dt>
                    <dd className="text-sm font-medium">
                      {deal.stage_history.length > 0
                        ? Math.floor(
                            (new Date().getTime() -
                              new Date(
                                deal.stage_history[0].created_at
                              ).getTime()) /
                              (1000 * 60 * 60 * 24)
                          )
                        : 0}{" "}
                      days
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm text-gray-500">Stage Changes</dt>
                    <dd className="text-sm font-medium">
                      {deal.stage_history.length} times
                    </dd>
                  </div>
                </dl>
              </Card>

              {/* Actions */}
              <Card className="p-6">
                <h3 className="text-lg font-semibold mb-4">Actions</h3>
                <div className="space-y-2">
                  <Link href={route("pipeline.index")} className="block">
                    <Button variant="outline" className="w-full">
                      View in Pipeline
                    </Button>
                  </Link>
                  <Link
                    href={route("companies.show", deal.company.id)}
                    className="block"
                  >
                    <Button variant="outline" className="w-full">
                      View Company
                    </Button>
                  </Link>
                  {deal.primary_contact && (
                    <Link
                      href={route("contacts.show", deal.primary_contact.id)}
                      className="block"
                    >
                      <Button variant="outline" className="w-full">
                        View Contact
                      </Button>
                    </Link>
                  )}
                </div>
              </Card>
            </div>
          </div>
        </div>
      </div>
    </AuthenticatedLayout>
  );
}
  1. Add formatDateTime utility:
typescript
// In resources/js/lib/utils.ts
export function formatDateTime(date: string): string {
  return new Date(date).toLocaleString("en-US", {
    year: "numeric",
    month: "short",
    day: "numeric",
    hour: "2-digit",
    minute: "2-digit",
  });
}

Expected Result ​

bash
# Visit deal show page
open http://localhost/deals/1

# Expected:
# - Complete deal information
# - Stage history timeline
# - Weighted value calculation
# - Links to related company/contact
# - Quick stats showing days in stage
# - Edit button in header

Why It Works ​

The Show view displays all deal data including relationships loaded via eager loading in the controller. The stage history section renders a timeline showing every stage transition with who moved it and when.

Weighted value is calculated client-side by multiplying the deal amount by the current stage's probability, giving a realistic forecast of expected revenue.

Troubleshooting ​

  • Stage history empty — Verify stageHistory relationship is loaded in controller
  • Weighted value NaN — Ensure probability column exists and contains numeric values
  • formatDateTime undefined — Add function to utils.ts and import

Step 8: Test Complete Workflow (~10 min) ​

Goal ​

Verify the entire deals system works end-to-end.

Actions ​

  1. Test Pipeline Board:
bash
# 1. Visit pipeline
open http://localhost/pipeline

# 2. Drag a deal from "New" to "In Progress"
# Expected: Card moves, page reloads, history created

# 3. Check metrics
# Expected: Weighted forecast updates based on new stage probability
  1. Test Deal Creation:
bash
# 1. Click "New Deal"
open http://localhost/deals/create

# 2. Fill form:
# - Title: "Enterprise Software License"
# - Amount: 50000
# - Company: Select existing
# - Stage: "New"
# - Close Date: Next month

# 3. Submit
# Expected: Deal created, redirects to show page, history record exists
  1. Test Deal Show Page:
bash
# 1. View deal details
open http://localhost/deals/1

# Expected:
# - All information displayed
# - Stage history shows creation + any moves
# - Weighted value calculated correctly
# - Links to company/contact work
  1. Test Authorization:
bash
sail artisan tinker
$user = User::find(2);  # Different team
$deal = Deal::first();
Gate::forUser($user)->authorize('view', $deal);
# Expected: AuthorizationException (different team)

Expected Result ​

✅ Complete working deals system:

  • Pipeline board displays all deals grouped by stage
  • Drag-and-drop moves deals and creates history
  • Deal CRUD operations work with validation
  • Authorization prevents cross-team access
  • Weighted forecasts calculate correctly
  • Stage history tracks all transitions

Why It Works ​

The complete system integrates controllers, policies, eager loading, form validation, and React UI into a cohesive workflow. Team-scoped queries ensure data isolation, authorization policies prevent unauthorized access, and stage history tracking provides an audit trail for every deal movement.

Troubleshooting ​

  • Drag-and-drop not working — Check browser console for JavaScript errors, verify @dnd-kit installed
  • Authorization fails unexpectedly — Clear policy cache: sail artisan optimize:clear
  • Metrics incorrect — Verify pipeline_stages.probability column has correct values (0-100)

Exercises ​

Exercise 1: Add Deal Notes ​

Goal: Learn to add supplemental data to existing features

Add a notes section to the Deal Show page allowing team members to add timestamped comments about the deal.

Requirements:

  • Create deal_notes table with deal_id, user_id, note, timestamps
  • Add DealNote model with relationships
  • Create form component on Deal Show page
  • Display notes in reverse chronological order
  • Show author name and timestamp for each note

Validation: Notes should display below stage history with author attribution and cannot be empty

Exercise 2: Add Stage-Specific Fields ​

Goal: Understand dynamic form fields based on state

Add stage-specific required fields that only show when a deal reaches certain stages.

Requirements:

  • When deal moves to "In Progress": Require estimated_hours field
  • When deal moves to "Won": Require won_date and contract_number fields
  • When deal moves to "Lost": Require lost_reason field
  • Validate these fields only when moving to those stages
  • Display stage-specific data on Deal Show page

Validation: Attempting to move to "Won" without contract number should fail with clear error message

Exercise 3: Bulk Stage Updates ​

Goal: Practice batch operations and optimistic UI updates

Add ability to select multiple deals and move them all to a new stage at once.

Requirements:

  • Add checkboxes to pipeline cards
  • Show "Move Selected" button when deals are checked
  • Allow selecting target stage from dropdown
  • Update all selected deals in one transaction
  • Create stage history for each deal
  • Show success message with count of deals moved

Validation: Moving 3 deals from "New" to "In Progress" should create 3 history records and update 3 deals

Wrap-up ​

Congratulations! You've built a professional deals management system with a visual Kanban pipeline board. Your CRM now has:

✅ Complete Deal CRUD with team-scoped authorization
✅ Visual Kanban pipeline displaying deals grouped by stage
✅ Drag-and-drop functionality for smooth stage transitions
✅ Stage history tracking creating immutable audit trails
✅ Weighted forecasting showing realistic revenue projections
✅ Eager loading preventing N+1 queries on all views
✅ Relational forms linking deals to companies and contacts
✅ Authorization policies ensuring team data isolation

You've mastered advanced Laravel and React patterns including drag-and-drop interfaces, complex eager loading, and real-time metrics calculation. The Deals module is the heart of any CRM system—you've built it with production-ready code.

What's next? In Chapter 17, you'll design the Tasks module allowing users to create to-do items linked to deals, contacts, and companies. You'll learn about polymorphic relationships enabling tasks to belong to multiple entity types.

Further Reading ​

Code Samples: View complete implementations in /code/build-crm-laravel-12/chapter-16/