shahzaibahmadd/fsms-dd

Purpose and Entry Points

This is a Laravel field-service/maintenance management system for machines, service tickets, technician assignment, work/spare-part tracking, customer approval, invoicing, and reporting. HTTP entry points split browser workflows from programmatic APIs at routes/web.php and routes/api.php; the public PHP front controller is public/index.php. Scheduled/CLI work enters through artisan and routes/console.php.

Delivery Boundaries

Web controllers render role-oriented Blade dashboards and ticket/machine views, while API controllers expose equivalent operational capabilities with request validation, DTOs, and resources. Key boundaries are app/Http/Controllers/Web/Ticket/TicketController.php, app/Http/Controllers/Api/Ticket/TicketController.php, and app/Http/Resources/Ticket/TicketResource.php. Controllers should remain adapters: validated requests feed DTO/service operations; API responses are normalized through resources and response traits.

Identity, Authorization, and Operational Roles

Users have technician and customer profiles, with administrative user/role management. Authorization is enforced through role middleware and permission services, centered on app/Models/User.php, app/Http/Middleware/RoleAccess.php, and app/Services/Admin/RolePermissionService.php. Authentication configuration includes Laravel auth, Sanctum, and JWT configuration (config/auth.php, config/sanctum.php, config/jwt.php); permission schema/configuration is present in database/migrations/2026_07_30_123046_create_permission_tables.php and config/permission.php.

Ticket Lifecycle and Assignment

Tickets are the core workflow aggregate: creation, priority evaluation/override, status transitions/history, assignment or reassignment, progress, and completion. The main orchestration services are app/Services/Ticket/TicketService.php, app/Services/Assignment/AssignmentService.php, and app/Services/ProgressTracking/ProgressService.php. Assignment is explicitly strategy-based, separating manual versus automatic selection through app/Services/Strategies/AssignmentStrategyFactory.php, app/Services/Strategies/AutoAssignmentStrategy.php, and app/Services/Strategies/ManualAssignmentStrategy.php; availability is managed separately by app/Services/TechnicianAvailability/TechnicianAvailabilityService.php.

Domain Persistence and Work Execution

Eloquent models and migrations define a relational domain around tickets, machines, assignments, technicians/customers, logs, parts, invoices, and maintenance schedules. Core records are app/Models/Ticket.php, app/Models/TicketAssignment.php, and app/Models/machine.php; schema evolution is under database/migrations/. Technician execution adds time/work logs and consumed spare parts via app/Services/WorkLog/WorkLogService.php, app/Models/WorkLog.php, and app/Models/TicketSparePart.php. Status enums, history traits, and transition exceptions indicate lifecycle integrity is a domain concern.

Maintenance, Approval, and Financial Flow

Preventive-maintenance schedules generate due-work signals, while completed work is customer-approved or rejected before invoice processing. This chain is represented by app/Services/Maintenance/MaintenanceService.php, app/Services/CustomerApproval/ApprovalService.php, and app/Services/Invoice/InvoiceService.php. Invoice totals are abstracted behind a calculator interface and standard implementation in app/Services/Interfaces/InvoiceCalculatorInterface.php and app/Services/Calculation/StandardInvoiceCalculator.php; invoice/PDF output uses app/Jobs/GenerateInvoicePdfJob.php and resources/views/pdf/invoice.blade.php.

Events, Async Processing, and Notifications

Domain events decouple lifecycle changes from side effects: ticket creation/assignment/status/completion and maintenance due events live in app/Events/. Listeners trigger invoice generation and stakeholder notifications, including app/Listeners/GenerateInvoiceListener.php, app/Listeners/SendTechnicianAssignmentNotification.php, and app/Listeners/NotifyCustomerOfCompletion.php. Laravel queues support deferred PDF generation and weekly reporting (app/Jobs/GenerateInvoicePdfJob.php, app/Jobs/SendWeeklyReportEmailJob.php); notifications depend on configured mail/queue infrastructure in config/mail.php and config/queue.php.

Reporting, Observability, and Runtime

Financial and performance reporting are service implementations behind report-generation abstractions: app/Services/Report/FinancialReportService.php, app/Services/Report/PerformanceReportService.php, and app/Services/Interfaces/ReportGeneratorInterface.php. Request/error logging has dedicated models/services (app/Models/RequestLogs.php, app/Services/ErrorLogging/ErrorLoggingService.php). Runtime is PHP/Laravel with Eloquent database, filesystem storage, cache/session, queue, mail, and optional broadcasting configured under config/; Vite-managed frontend assets originate at resources/js/app.js.