# shahzaibahmadd/fsms-dd architecture

> Architecture diagram of the GitHub repository shahzaibahmadd/fsms-dd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shahzaibahmadd/fsms-dd
- Repository: https://github.com/shahzaibahmadd/fsms-dd

## Overview

#### 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`.

Main entry points: [`app/Services/Ticket/TicketService.php`](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Ticket/TicketService.php) (Ticket service), [`app/Http/Controllers/Api/Ticket/TicketController.php`](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Controllers/Api/Ticket/TicketController.php) (API ticket controller), [`app/Models/Ticket.php`](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Models/Ticket.php) (Ticket & assignment records), [`app/Http/Controllers/Web/Ticket/TicketController.php`](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Controllers/Web/Ticket/TicketController.php) (Web ticket controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Delivery"]
  node_web["Browser routes<br/>Laravel routes<br/>[web.php]"]
  node_api["API routes<br/>Laravel routes<br/>[api.php]"]
  node_web_ticket_controller["Web ticket controller<br/>web controller"]
  node_api_ticket_controller["API ticket controller<br/>API controller"]
  node_ticket_resource["Ticket resource<br/>API resource<br/>[TicketResource.php]"]
  node_cli_scheduler["CLI &amp; scheduler<br/>Laravel console<br/>[console.php]"]
end

subgraph group_access["Identity &amp; Access"]
  node_access_control["Role access<br/>middleware<br/>[RoleAccess.php]"]
  node_users_roles[("Users &amp; permissions<br/>identity domain<br/>[User.php]")]
  node_role_permissions["Role permission service<br/>authorization service"]
end

subgraph group_lifecycle["Ticket Lifecycle"]
  node_ticket_service["Ticket service<br/>workflow service<br/>[TicketService.php]"]
  node_assignment_service["Assignment service<br/>workflow service"]
  node_assignment_strategy{{"Assignment strategies<br/>strategy factory"}}
  node_availability["Technician availability<br/>availability service"]
  node_ticket_domain[("Ticket &amp; assignment records<br/>Eloquent domain<br/>[Ticket.php]")]
end

subgraph group_execution["Execution &amp; Finance"]
  node_work_execution["Work logs &amp; spare parts<br/>execution service<br/>[WorkLogService.php]"]
  node_maintenance["Maintenance service"]
  node_approval["Customer approval<br/>approval service"]
  node_invoicing["Invoice service<br/>financial service<br/>[InvoiceService.php]"]
end

subgraph group_async["Events &amp; Async"]
  node_invoice_pdf_job["Invoice PDF job<br/>queued job"]
  node_events_listeners["Lifecycle events &amp; listeners<br/>event pipeline"]
  node_reporting["Financial &amp; performance reports<br/>report services"]
end

node_runtime[("Laravel infrastructure<br/>runtime services")]

node_web -->|"dispatches to"| node_web_ticket_controller
node_api -->|"dispatches to"| node_api_ticket_controller
node_web_ticket_controller -->|"authorized by"| node_access_control
node_api_ticket_controller -->|"authorized by"| node_access_control
node_access_control -->|"checks permissions"| node_role_permissions
node_role_permissions -->|"uses"| node_users_roles
node_web_ticket_controller -->|"invokes"| node_ticket_service
node_api_ticket_controller -->|"invokes"| node_ticket_service
node_api_ticket_controller -->|"returns"| node_ticket_resource
node_ticket_service -->|"persists lifecycle"| node_ticket_domain
node_ticket_service -->|"assigns tickets"| node_assignment_service
node_assignment_service -->|"selects strategy"| node_assignment_strategy
node_assignment_strategy -->|"evaluates availability"| node_availability
node_assignment_service -->|"records assignment"| node_ticket_domain
node_work_execution -->|"records work and parts"| node_ticket_domain
node_maintenance -->|"creates due work"| node_ticket_service
node_ticket_service -.->|"emits lifecycle events"| node_events_listeners
node_events_listeners -.->|"completion notification"| node_approval
node_approval -->|"approved work"| node_invoicing
node_invoicing -.->|"queues PDF generation"| node_invoice_pdf_job
node_events_listeners -.->|"triggers invoice generation"| node_invoice_pdf_job
node_cli_scheduler -->|"runs scheduled work"| node_maintenance
node_cli_scheduler -.->|"runs weekly reports"| node_reporting
node_invoice_pdf_job -->|"uses queue, mail, storage"| node_runtime
node_ticket_domain -->|"stored through Eloquent"| node_runtime

click node_web "https://github.com/shahzaibahmadd/fsms-dd/blob/main/routes/web.php"
click node_api "https://github.com/shahzaibahmadd/fsms-dd/blob/main/routes/api.php"
click node_web_ticket_controller "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Controllers/Web/Ticket/TicketController.php"
click node_api_ticket_controller "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Controllers/Api/Ticket/TicketController.php"
click node_ticket_resource "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Resources/Ticket/TicketResource.php"
click node_cli_scheduler "https://github.com/shahzaibahmadd/fsms-dd/blob/main/routes/console.php"
click node_access_control "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Middleware/RoleAccess.php"
click node_users_roles "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Models/User.php"
click node_role_permissions "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Admin/RolePermissionService.php"
click node_ticket_service "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Ticket/TicketService.php"
click node_assignment_service "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Assignment/AssignmentService.php"
click node_assignment_strategy "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Strategies/AssignmentStrategyFactory.php"
click node_availability "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/TechnicianAvailability/TechnicianAvailabilityService.php"
click node_ticket_domain "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Models/Ticket.php"
click node_work_execution "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/WorkLog/WorkLogService.php"
click node_maintenance "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Maintenance/MaintenanceService.php"
click node_approval "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/CustomerApproval/ApprovalService.php"
click node_invoicing "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Invoice/InvoiceService.php"
click node_invoice_pdf_job "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Jobs/GenerateInvoicePdfJob.php"
click node_events_listeners "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Listeners/GenerateInvoiceListener.php"
click node_reporting "https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Report/FinancialReportService.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_api,node_web_ticket_controller,node_api_ticket_controller,node_ticket_resource,node_cli_scheduler toneBlue
class node_access_control,node_users_roles,node_role_permissions toneAmber
class node_ticket_service,node_assignment_service,node_assignment_strategy,node_availability,node_ticket_domain toneMint
class node_work_execution,node_maintenance,node_approval,node_invoicing toneRose
class node_invoice_pdf_job,node_events_listeners,node_reporting toneIndigo
class node_runtime toneNeutral
```

## Components

### Entry & Delivery

- [Browser routes](https://github.com/shahzaibahmadd/fsms-dd/blob/main/routes/web.php): Laravel routes · Role-oriented Blade workflows. · `routes/web.php`
- [API routes](https://github.com/shahzaibahmadd/fsms-dd/blob/main/routes/api.php): Laravel routes · Programmatic operational endpoints. · `routes/api.php`
- [Web ticket controller](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Controllers/Web/Ticket/TicketController.php): web controller · `app/Http/Controllers/Web/Ticket/TicketController.php`
- [API ticket controller](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Controllers/Api/Ticket/TicketController.php): API controller · `app/Http/Controllers/Api/Ticket/TicketController.php`
- [Ticket resource](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Resources/Ticket/TicketResource.php): API resource · Normalizes ticket API responses. · `app/Http/Resources/Ticket/TicketResource.php`
- [CLI & scheduler](https://github.com/shahzaibahmadd/fsms-dd/blob/main/routes/console.php): Laravel console · `routes/console.php`

### Identity & Access

- [Role access](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Http/Middleware/RoleAccess.php): middleware · Enforces role-based authorization. · `app/Http/Middleware/RoleAccess.php`
- [Users & permissions](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Models/User.php): identity domain · `app/Models/User.php`
- [Role permission service](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Admin/RolePermissionService.php): authorization service · `app/Services/Admin/RolePermissionService.php`

### Ticket Lifecycle

- [Ticket service](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Ticket/TicketService.php): workflow service · Creates tickets and governs priority and status lifecycle. · `app/Services/Ticket/TicketService.php`
- [Assignment service](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Assignment/AssignmentService.php): workflow service · `app/Services/Assignment/AssignmentService.php`
- [Assignment strategies](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Strategies/AssignmentStrategyFactory.php): strategy factory · Selects manual or automatic technician assignment. · `app/Services/Strategies/AssignmentStrategyFactory.php`
- [Technician availability](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/TechnicianAvailability/TechnicianAvailabilityService.php): availability service · `app/Services/TechnicianAvailability/TechnicianAvailabilityService.php`
- [Ticket & assignment records](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Models/Ticket.php): Eloquent domain · Persists tickets, assignments, machines, and lifecycle history. · `app/Models/Ticket.php`

### Execution & Finance

- [Work logs & spare parts](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/WorkLog/WorkLogService.php): execution service · `app/Services/WorkLog/WorkLogService.php`
- [Maintenance service](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Maintenance/MaintenanceService.php): maintenance service · Generates due-work signals from preventive schedules. · `app/Services/Maintenance/MaintenanceService.php`
- [Customer approval](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/CustomerApproval/ApprovalService.php): approval service · `app/Services/CustomerApproval/ApprovalService.php`
- [Invoice service](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Invoice/InvoiceService.php): financial service · Calculates and processes approved work invoices. · `app/Services/Invoice/InvoiceService.php`

### Events & Async

- [Invoice PDF job](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Jobs/GenerateInvoicePdfJob.php): queued job · Generates invoice PDF output. · `app/Jobs/GenerateInvoicePdfJob.php`
- [Lifecycle events & listeners](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Listeners/GenerateInvoiceListener.php): event pipeline · Publishes lifecycle changes and triggers notifications/invoicing. · `app/Listeners/GenerateInvoiceListener.php`
- [Financial & performance reports](https://github.com/shahzaibahmadd/fsms-dd/blob/main/app/Services/Report/FinancialReportService.php): report services · `app/Services/Report/FinancialReportService.php`

### Other components

- **Laravel infrastructure**: runtime services · Eloquent database, queue, mail, storage, cache, and sessions.

## Connections

- Browser routes → Web ticket controller: dispatches to
- API routes → API ticket controller: dispatches to
- Web ticket controller → Role access: authorized by
- API ticket controller → Role access: authorized by
- Role access → Role permission service: checks permissions
- Role permission service → Users & permissions: uses
- Web ticket controller → Ticket service: invokes
- API ticket controller → Ticket service: invokes
- API ticket controller → Ticket resource: returns
- Ticket service → Ticket & assignment records: persists lifecycle
- Ticket service → Assignment service: assigns tickets
- Assignment service → Assignment strategies: selects strategy
- Assignment strategies → Technician availability: evaluates availability
- Assignment service → Ticket & assignment records: records assignment
- Work logs & spare parts → Ticket & assignment records: records work and parts
- Maintenance service → Ticket service: creates due work
- Ticket service → Lifecycle events & listeners: emits lifecycle events
- Lifecycle events & listeners → Customer approval: completion notification
- Customer approval → Invoice service: approved work
- Invoice service → Invoice PDF job: queues PDF generation
- Lifecycle events & listeners → Invoice PDF job: triggers invoice generation
- CLI & scheduler → Maintenance service: runs scheduled work
- CLI & scheduler → Financial & performance reports: runs weekly reports
- Invoice PDF job → Laravel infrastructure: uses queue, mail, storage
- Ticket & assignment records → Laravel infrastructure: stored through Eloquent