Garage Module — User Guide
All guides

Garage Module — User Guide

Fleet, drivers, maintenance, and compliance.

ProductVertex ERP
ModuleGarage (`modules/garage`)
AudienceFleet managers, operations staff, maintenance supervisors, and compliance officers
FormatHTML + Mermaid diagrams

1. Overview

The Garage module manages organizational fleet operations: vehicles, drivers, handover assignments, maintenance, compliance documents, fuel, accidents, violations, and operational alerts.

Area Capabilities
Fleet master Vehicles and drivers
Operations Assignments (check-out / return), fuel logs
Maintenance Jobs and workshops
Compliance Vehicle licenses, insurance, technical inspections
Incidents Accidents and traffic violations
Monitoring Alerts, dashboard, reports
flowchart LR V[Vehicle] --> A[Assignment] D[Driver] --> A V --> M[Maintenance] V --> Doc[License / Insurance / Inspection] V --> Acc[Accidents / Violations] Doc --> Alert[Alerts] M --> Alert

Cross-module note: Driver identity can reference an employee id. Live HR/Inventory/Finance posting is largely planned; costs and parts references are stored in Garage today. See Integrations.

2. Getting started

2.1 Recommended setup order

flowchart TD A[Grant Garage permissions] --> B[Alert settings Host] B --> C[Workshops] C --> D[Vehicles] D --> E[Drivers] E --> F[Licenses insurance inspections] F --> G[Assignments] G --> H[Maintenance and fuel] H --> I[Accidents and violations]
  1. Grant Garage permissions to roles.
  2. Configure alert settings (Host manages shared alert settings).
  3. Create workshops.
  4. Register vehicles.
  5. Register drivers (with driving license data).
  6. Add vehicle licenses, insurance, and inspections.
  7. Start assignments, maintenance, and fuel logging.
  8. Record accidents/violations as needed.
  9. Use dashboard, alerts, and reports for monitoring.

2.2 Main navigation

Menu Path Purpose
Dashboard /garage/overview Fleet KPIs and queues
Vehicles /garage/vehicles Fleet register (+ detail)
Drivers /garage/drivers Driver register (+ detail)
Assignment and handover /garage/assignments Check-out / return
Maintenance /garage/maintenance Jobs and workshops
Licenses and insurance /garage/licenses Licenses, insurance, inspections
Accidents /garage/accidents Accident cases
Violations /garage/violations Traffic violations
Alerts /garage/alerts Expiry and ops alerts
Reports /garage/reports Operational reports
Integrations /garage/integrations Planned connection roadmap

3. Vehicles

Key data

Group Examples
Identity Plate number, VIN, engine number, manufacturer, model, year, type, color
Specs Seats, fuel type, tank capacity, engine CC, weight, transmission
Operations Operational status, current driver, department, current km
Purchase Purchase date/value/vendor, depreciation, condition, warranty
Documents Document labels on the vehicle file

Operational statuses

Available, Assigned, Under maintenance, Out of service, Decommissioned

Detail tabs

Info, Purchase, Operations, Documents, History (related maintenance, fuel, accidents, violations, assignments, licenses, insurance).

Plate number is required. Fuel can be logged from vehicle detail.

flowchart TD A[Create vehicle Available] --> B[Assign to driver] B --> C[Status Assigned] C --> D[Open maintenance] D --> E[Status Under maintenance] E --> F[Complete maintenance] F --> G[Back to Available or Assigned]

4. Drivers

Drivers link operational driving data to an employee identity.

Group Examples
Identity Employee id, name, national id, department, job title, contract end
Driving license Number, issuer, issue/expiry, class, status
Status Available, Assigned to vehicle, On leave, On mission, Contract ended

License classes typically include light, heavy, public, motorcycle. License statuses: valid, expired, cancelled.

Employee pickers may use a seeded HR list until live HR lookup is fully wired. Unlinking a driver removes Garage linkage without deleting HR employee master data.

Driver detail shows profile and related assignments, violations, and accidents.

5. Assignments and handover

Assignments record vehicle check-out to a receiver and later return.

Receive fields

Vehicle, receiver (name / employee id), responsible person, receive date, assignment type (allocation or mission), odometer, fuel %, condition, notes.

Return fields

Return date, odometer, fuel %, condition, notes.

Statuses used in UI

Status Meaning
Open Vehicle checked out
Closed Returned
flowchart TD A[Create assignment Open] --> B[Vehicle Assigned] B --> C[Driver Assigned to vehicle] C --> D[Return] D --> E[Assignment Closed] E --> F[Vehicle Available] E --> G[Driver Available]

Rules of thumb: vehicle and receiver required; return km should not be less than receive km. Closing an assignment typically frees the vehicle and driver statuses for fleet availability.

API note: A longer workflow (Requested → Approved → CheckedOut → Returned) exists on the backend. The main UI path used today is Open → Closed (checked out then returned).

6. Maintenance and workshops

Workshops

Name, type (for example external), commercial registration, contract details, contact, specialty, hours, quality rating. Used as the service provider on maintenance jobs.

Maintenance jobs

Field group Examples
Header Vehicle, optional driver, workshop, type, dates, status, km, description
Cost Labor cost, parts list (JSON)
Schedule Interval km/months, next due date
Fault Reason, severity, location, repair type, fault date
Checklist Checklist items

Types: Periodic, Emergency, Preventive
Statuses: Pending, In progress, Completed, Cancelled
Severities: Minor, Medium, Critical, Total stop

Opening maintenance often marks the vehicle under maintenance; completing it returns the vehicle toward available or assigned based on current assignment.

Maintenance screen typically has tabs for jobs and workshops.

flowchart TD A[Create job Pending] --> B[In progress] B --> C[Completed] A --> D[Cancelled] B --> E[Vehicle Under maintenance] C --> F[Restore vehicle status]

7. Licenses, insurance, and inspections

Managed mainly under Licenses and insurance (combined screen with tabs).

Vehicle licenses

Number, issuer, issue/expiry, type/category, fees, status.

Insurance

Policy, company, type (comprehensive, third party, driver), dates, premium, payment, coverage, emergency phone, status.

Technical inspections

Center, date, expiry, result, report number, cost.

Document statuses: Valid, Expired, Cancelled, Under renewal
Inspection results: Accepted, Rejected, Needs repair

Driver licenses are stored on the driver record, not as vehicle license rows.

8. Fuel logs

Fuel entries record vehicle, date, liters, cost, station, and odometer. There is no separate status. Saving a fuel log typically updates the vehicle last fuel date and current km. Access fuel entry from vehicle detail; reports include fuel summaries.

9. Accidents

Accident cases capture vehicle, driver, date/time, location, type, description, cause, status, police report, other party, injuries, damages, insurance/compensation/legal fields.

Statuses: Under preparation, Under investigation, Closed, Under compensation

Use the accident list and detail pages to track damages and claim progress.

10. Violations

Traffic violations include number, vehicle, driver, date/time, location, type, amount/discount, issuer, due/paid dates, payment/receipt, and objection block.

Statuses: Unpaid, Partially paid, Fully paid, Under objection, Cancelled

11. Alerts

Alerts are generated from fleet data and alert settings (maintenance due/overdue, license/insurance/inspection expiry, driver license/contract, violations, accidents, and related ops events).

Topic Guidance
Settings Shared alert settings are Host-managed
Channels / days before Configured per alert key
Acknowledge Session-oriented in the current UI (may not persist server-side)
Groups Licenses, insurance, inspection, drivers, maintenance, operations, accidents, violations
flowchart TD A[Documents and ops data] --> B[Alert rules] B --> C[Alerts list] C --> D[Review and act]

12. Dashboard and reports

Dashboard

KPIs such as fleet counts by status, open assignments, open maintenance, unpaid violations, open accidents, unread alerts, cost rollups, expiring documents, and an alert feed. Role lenses may emphasize manager, operations, maintenance, or documents views.

Reports

Client-side report tabs for vehicles, drivers, fuel, maintenance, documents, accidents, violations, and costs, with CSV/print style export for cost summaries. Use reports for operational review rather than formal GL posting.

13. Integrations

The Integrations screen documents planned connections:

Area Intent
ERP users/permissions Align roles with existing auth
HR Live driver identity/contract sync (picker may still use seed until wired)
Warehouse / Inventory Spare parts availability and issue on maintenance
Finance Post fuel, maintenance, premiums, paid violations, accident costs
Procurement Vehicle purchases and external workshops as vendors

Treat Integrations as a roadmap page until each connection is enabled in your environment.

14. Permissions summary

Permission group: Garage.

Resource Abilities
Vehicles Create, Update, Delete
Drivers Create, Update, Delete
Assignments Create, Update, Delete
Licenses Create, Update, Delete
Insurance Create, Update, Delete
Inspections Create, Update, Delete
Accidents Create, Update, Delete
Violations Create, Update, Delete
Maintenance Create, Update, Delete
Workshops Create, Update, Delete
Fuel Create, Update, Delete
Dashboard Access (also used for alerts/reports/integrations menu gates)

Parent menu opens with Dashboard or Vehicles permission.

Appendix A — Quick procedures

A.1 Put a vehicle into service

  1. Create vehicle (Available).
  2. Add license, insurance, and inspection.
  3. Create driver with valid driving license.
  4. Create assignment (Open) → vehicle Assigned.

A.2 Return a vehicle

  1. Open assignment.
  2. Enter return km/fuel/condition.
  3. Set Closed / return.
  4. Confirm vehicle and driver return to Available.

A.3 Run maintenance

  1. Ensure workshop exists.
  2. Create job (Pending/In progress) with parts and labor.
  3. Complete job and verify vehicle status restored.

A.4 Track compliance

  1. Keep license/insurance/inspection dates current.
  2. Review Alerts for upcoming expiries.
  3. Use Reports → documents for period review.

Appendix B — Operating notes

Topic Guidance
HR link Employee id is stored; confirm whether your build uses live HR lookup
Assignment workflow UI focuses on Open/Closed; request/approve APIs may exist unused
Alerts Settings are Host-scoped; acknowledge may be session-only
Finance/Inventory Costs and parts are recorded locally until integrations go live

Appendix C — Document control

Item Value
Title Garage Module User Guide
Source of truth modules/garage and frontend/src/app/modules/garage
Format Markdown + Mermaid (PDF edition embeds rendered figures)
Screenshots Not included (by design)

This guide describes functional capabilities of the Garage module as implemented in the Vertex ERP codebase. UI labels may appear in English or Arabic depending on language settings.

Vertex ERP documentation. Generated from Markdown sources in docs/.