Fleet & Driver Management
Relevant source files
The following files were used as context for generating this wiki page:
The Fleet & Driver Management system is a core module of the Outmanage logistics platform responsible for managing the vehicles (Armadas) and personnel (Drivers) involved in outbound shipments. This system ensures that every delivery or pickup is associated with a valid vehicle and an authorized driver, facilitating accountability through AI-powered plate verification and comprehensive audit logging.
This module integrates deeply with the Shipment Weighing and Report systems to track vehicle performance, monitor delivery status (ANTAR or JEMPUT), and generate operational insights such as the "Most Active Vehicle" report.
Sources: CLAUDE.md, prisma/schema.prisma:343-370, comprehensive-swagger-api.json
Architecture and Data Models
The system relies on three primary entities defined in the database schema: Armada, Driver, and Shipment. The relationship is structured so that a Shipment acts as the transaction record linking a vehicle and a driver to specific delivery orders.
Entity Relationships
The following ER diagram illustrates how fleet and driver data relates to the broader logistics flow:
Diagram shows the relationship between vehicles, drivers, and the shipment records they fulfill.
Sources: prisma/schema.prisma:343-376
Data Model Definitions
| Model | Field | Type | Description |
|---|---|---|---|
| Armada | id_sl | String | Legacy system ID for cross-platform mapping. |
plateNumber | String | Unique license plate identifier. | |
model | String | Vehicle make or model. | |
| Driver | name | String | Full name of the driver. |
deletedAt | DateTime | Timestamp for soft-deletion/archiving. | |
| Shipment | tally | String | Personnel responsible for counting/loading. |
kenek | String | Assistant driver or helper assigned to the trip. |
Sources: prisma/schema.prisma:343-376, comprehensive-swagger-api.json:434-455
Fleet Management Operations
The Armada sub-module handles vehicle registration and lifecycle tracking. It supports standard CRUD operations and maintains a deletedAt field for soft deletion. Vehicles are categorized as "Active" or "Archived."
Vehicle Plate Verification
A critical feature is the AI-powered plate verification. When a vehicle arrives at a warehouse, a photo is taken and uploaded. The system uses Google Gemini AI to extract the plate number and compare it against the expected plateNumber in the Armada record.
Flowchart of the vehicle verification logic before shipment completion.
Sources: src/services/shipmentService.ts:1335-1393, README.md:167-200
Fleet API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/armadas | GET | Retrieve paginated list of vehicles. |
/api/armadas | POST | Create a new vehicle record. |
/api/armadas/{id} | PUT | Update vehicle details. |
/api/armadas/logs | GET | View audit trail for vehicle changes. |
Sources: comprehensive-swagger-api.json:626-724
Driver Management Operations
Drivers are managed through the driverController.ts. The system provides endpoints for both administrative management (CRUD) and operational selection (Active Driver lists for shipment assignment).
Logic and Validation
- Pagination: Results are limited to 1-100 items per page to ensure API performance.
- Soft Deletion: Drivers are not permanently removed; they are marked with a
deletedAttimestamp to preserve historical shipment data. - Active Status: The
getActiveDriversfunction filters out any drivers with adeletedAttimestamp.
Sources: src/controllers/driverController.ts:10-40, prisma/schema.prisma:353-359
Driver API Endpoints
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/api/drivers | GET | page, limit, search | Paginated list of all drivers. |
/api/drivers/active | GET | None | List of drivers available for assignment. |
/api/drivers | POST | name | Register a new driver. |
Sources: src/controllers/driverController.ts:10-140
Shipment Assignment and Reporting
The system tracks vehicle and driver performance through the reportService.ts. This data is visualized on the main dashboard to provide real-time metrics on fleet utilization.
KPI Metrics
The system calculates several key performance indicators for the fleet:
- Vehicle Usage Count: Number of unique vehicles used in a specific timeframe.
- Most Active Vehicle: A ranking of vehicles based on the number of completed shipments.
- Top Verified Armadas: Vehicles that consistently pass AI plate verification with photos.
Sources: src/services/reportService.ts:119-150, src/types/report.ts:210-230
Assignment Lifecycle
Sequence of assigning a driver and vehicle to a new logistics shipment.
Sources: src/services/shipmentService.ts:400-450
Audit Logging
Every change to the fleet or driver data is recorded in dedicated log tables: ArmadaLog and DriverLog (inherited through UserLog structures in some contexts). These logs capture:
- The user who performed the action.
- The action type (CREATE, UPDATE, DELETE).
- JSON snapshots of
oldDataandnewData. - Technical descriptions of the change (e.g., "Tally changed from A to B").
Sources: prisma/schema.prisma:361-376, src/services/shipmentService.ts:1874-1882
Summary
Fleet & Driver Management in Outmanage provides a robust framework for vehicle and personnel oversight. By linking specific Armada and Driver IDs to shipments, the system maintains a high degree of operational security, further enhanced by AI-driven vehicle plate verification and detailed audit trails. This module serves as the logistical backbone for assigning accountability from warehouse departure to final customer delivery.