Car-Repairs-Shop/.github/copilot-instructions.md

Car Repairs Shop — AI agent working notes

This repo is a Laravel 12 app with Livewire (Volt + Flux UI), Tailwind, and Vite. The UI is primarily Livewire pages; a few classic controllers exist for resource routes. Tests use in-memory SQLite.

Architecture map

• Workflow-driven design: The app implements an 11-step automotive repair workflow from vehicle reception to delivery with status tracking, inspections, estimates, and customer notifications.
• Core domains live in app/Livewire/** and app/Models/** (Customers, Vehicles, Inventory, JobCards, Estimates, Diagnosis, WorkOrders, Timesheets, Users, Reports, CustomerPortal).
• WorkflowService (app/Services/WorkflowService.php) orchestrates the complete repair process with methods for each workflow step.
• InspectionChecklistService (app/Services/InspectionChecklistService.php) manages standardized vehicle inspections and comparison logic.
• Routes are in routes/web.php:
  • Root decides destination based on auth()->user()->isCustomer() → customers go to /customer-portal, admins/staff to /dashboard, guests to /login.
  • Admin/staff area uses admin.only + permission:* middleware. Customer portal uses auth only.
  • Volt pages registered via Volt::route('settings/...', 'settings.something').
• Middleware aliases are registered in bootstrap/app.php:
  • admin.only, role, permission point to custom classes in app/Http/Middleware. Route permission: strings are the canonical auth gates in this app.
• Settings use Spatie Laravel Settings (app/Settings/**, config/settings.php), e.g., app(\App\Settings\GeneralSettings::class) for shop phone/email in views.
• Blade components: anonymous components live under resources/views/components/**. Example: <x-layouts.customer-portal /> is backed by resources/views/components/layouts/customer-portal.blade.php.

11-Step Workflow Implementation

The system follows a structured automotive repair workflow:

1. Vehicle Reception → JobCard::STATUS_RECEIVED - Basic data capture, unique sequence numbers by branch (ACC/00212, KSI/00212)
2. Initial Inspection → JobCard::STATUS_INSPECTED - Standardized checklist via InspectionChecklistService
3. Service Assignment → JobCard::STATUS_ASSIGNED_FOR_DIAGNOSIS - Assign to Service Coordinator
4. Diagnosis → JobCard::STATUS_IN_DIAGNOSIS - Full diagnostic with timesheet tracking
5. Estimate → JobCard::STATUS_ESTIMATE_SENT - Detailed estimate with email/SMS notifications
6. Approval → JobCard::STATUS_APPROVED - Customer approval triggers team notifications
7. Parts Procurement → JobCard::STATUS_PARTS_PROCUREMENT - Inventory management and sourcing
8. Repairs → JobCard::STATUS_IN_PROGRESS - Work execution with timesheet tracking
9. Final Inspection → JobCard::STATUS_COMPLETED - Outgoing inspection with discrepancy detection
10. Delivery → JobCard::STATUS_DELIVERED - Customer pickup and satisfaction tracking
11. Archival - Document archiving and job closure

Conventions and patterns

• Status-driven workflow: Use JobCard::getStatusOptions() for consistent status handling. Each status corresponds to a workflow step.
• Role hierarchy: Service Supervisor → Service Coordinator → Technician. Use role helper methods like $user->isServiceCoordinator().
• Livewire pages reside under app/Livewire/{Area}/{Page}.php with views under resources/views/{area}/{page}.blade.php (Volt routes may point directly to views).
• Authorization:
  • Use admin.only to gate admin/staff routes.
  • Use permission:domain.action strings on routes (e.g., permission:customers.view, inventory.create). Keep naming consistent with existing routes.
• Branch-specific operations: All job cards have branch_code. Use JobCard::byBranch($code) scope for filtering.
• Customer Portal layout requires a jobCard prop. When using <x-layouts.customer-portal>, pass it explicitly:
  • Example: <x-layouts.customer-portal :job-card="$jobCard"> ... </x-layouts.customer-portal>
• Inspection system: Use InspectionChecklistService for standardized checklists. Incoming vs outgoing inspections are compared automatically.

Developer workflows

• Install & run (common):
  • PHP deps: composer install
  • Node deps: npm install
  • Generate key & migrate: php artisan key:generate && php artisan migrate --seed
  • Dev loop (servers + queue + logs + Vite): composer dev (runs: serve, queue:listen, pail, vite)
  • Asset build: npm run build
• Testing:
  • Run tests: ./vendor/bin/phpunit (uses in-memory SQLite per phpunit.xml)
  • Alternative: composer test (clears config and runs artisan test)
• Debugging:
  • Logs via Laravel Pail are included in composer dev. Otherwise: php artisan pail.

Routing and modules (examples)

Data Flow and State Management

• Status-Driven Design: Each workflow step corresponds to a specific JobCard status. Always use status constants from the model.
• Service Dependencies: WorkflowService orchestrates the complete flow, InspectionChecklistService handles standardized vehicle inspections.
• Customer Communication: Auto-notifications at each step keep customers informed of progress.
• Quality Control: Built-in inspection comparisons and quality alerts ensure consistent service delivery.
• Admin resources (with permissions):
  • Route::resource('customers', CustomerController::class)->middleware('permission:customers.view');
• Inventory area pages are Livewire classes under app/Livewire/Inventory/** and grouped under Route::prefix('inventory') with permission:inventory.*.
• Customer portal routes:
  • Route::prefix('customer-portal')->middleware(['auth'])->group(function () { Route::get('/status/{jobCard}', \\App\\Livewire\\CustomerPortal\\JobStatus::class)->name('customer-portal.status'); });

Testing notes (project-specific)

• Tests use in-memory SQLite; avoid relying on factories that don’t exist. Prefer lightweight stubs or create the minimal model records needed.
• For Blade/Livewire views using a layout slot, render the page view (not the layout) and pass required data. Example: View::make('livewire.customer-portal.job-status', ['jobCard' => $jobCard])->render();

Guardrails for agents

• When adding new admin routes, wire admin.only and appropriate permission:* middleware, and register Volt pages via Volt::route when applicable.
• Keep anonymous Blade components under resources/views/components/** and pass required props explicitly.
• Use app(\App\Settings\GeneralSettings::class) for shop metadata instead of hardcoding.
• Follow existing permission key patterns (domain.action).

If anything above is unclear or you need deeper details (e.g., settings schema, specific Livewire page conventions), propose a short diff or ask for a quick pointer to the relevant file.