FleetManagement.tsx
The navigation wrapper component that provides the pill-style navigation bar and routes between different Fleet Management modules.Purpose
- Renders the navigation header with pill-style buttons
- Handles client-side routing between fleet modules
- Passes navigation callbacks to child components
- Displays the appropriate module based on current URL path
Props
| Prop | Type | Description |
|---|---|---|
onNavigateToTracking | (loadId: string) => void | Callback when user wants to navigate to tracking page |
onNavigateToTractor | (tractorId: string) => void | Callback when user wants to navigate to tractor details |
Navigation Items
The component defines a static array of navigation items:| ID | Label | Icon | Route |
|---|---|---|---|
overview | Dashboard | LayoutDashboard | /fleet |
drivers | Driver Management | User | /fleet/drivers |
tractors | Tractor Management | Truck | /fleet/tractors |
trailers | Trailer Management | Container | /fleet/trailers |
pta | Predicted Time Available | Clock | /fleet/pta |
renderContent
Internal function that renders the appropriate child component based onrouter.pathname:
Styling
The navigation uses a modern “pills” style with:- Active state: Yellow gradient background with shadow
- Inactive state: Semi-transparent white with border
- Rounded full (pill shape)
- Hover transitions with shadow effects
UnifiedFleetDashboard.tsx
The main dashboard component that displays KPI cards, interactive maps, fleet panels, and search functionality.Purpose
- Display real-time fleet statistics (KPIs)
- Provide interactive map views for tractors, trailers, and drivers
- Enable search across drivers, vehicles, trailers, orders, and movements
- Show fleet summary panels with filterable lists
Dependencies
| Import | Purpose |
|---|---|
useUnifiedFleetData | Hook for fetching and managing fleet data |
ConnectionStatusIndicator | Shows SSE connection status |
LiveVehicleMap | Interactive tractor/vehicle map |
LiveTrailerMap | Interactive trailer map |
shadcn/ui components | Card, Button, Badge, Tabs, Input, Select |
State Management
UI State
UI State
| State | Type | Default | Purpose |
|---|---|---|---|
activeTab | string | 'dashboard' | Current tab (dashboard/alerts) |
searchQuery | string | '' | Search input value |
vehicleMetricFilter | 'all' | 'active' | 'inactive' | 'lowFuel' | 'all' | Vehicle filter |
mapView | 'tractors' | 'trailers' | 'drivers' | 'tractors' | Map view mode |
dispatcherFilter | string | 'all' | Dispatcher filter for tractors |
Search State
Search State
| State | Type | Purpose |
|---|---|---|
isSearching | boolean | Loading indicator for API search |
searchError | string | null | Error message from search |
searchResultIds | { drivers, vehicles, trailers } | IDs returned from order/movement search |
Data State
Data State
| State | Type | Purpose |
|---|---|---|
movements | any[] | Movements data for vehicle-load mapping |
orderIdToCustomerName | Map<string, string> | Cache of order ID to customer name |
Key useMemo Computations
vehicleToLoadMap
vehicleToLoadMap
Maps
vehicle_id to active load information for display in map popups.Returns: Map<string, { orderId, movementId, origin, destination, customerName }>Logic:- Iterates through movements
- Finds vehicle by matching
tractor_numbertomovement.tractor_id - Extracts pickup/delivery stops for origin/destination
- Gets customer name from order ID cache
driverIdToNameMap
driverIdToNameMap
Creates multiple mappings from various driver ID formats to full name.Returns:
Map<string, string>Maps by:driver_id(with/withoutdrv_prefix)source_id(with/withoutdrv_prefix)username- All in lowercase variants
filteredVehicles
filteredVehicles
Filters vehicles based on search query, metric filter, and dispatcher filter.Filters applied:
- Search result IDs (from API order/movement search)
- Client-side text search (vehicle_id, tractor_number, driver_id, driver name)
- Metric filter (all, active, inactive, lowFuel)
- Dispatcher filter
overallStatus
overallStatus
Determines aggregate connection status from all three data sources.Priority:
error > disconnected > connecting > connectedperformAPISearch
Debounced API search function for order/movement numbers.Important Implementation Details:
- Debounce delay: 500ms before API call is triggered
- Minimum query length: 3 characters
- Valid characters: Alphanumeric and hyphens only (
/^[a-zA-Z0-9\-]+$/)
API Endpoints Used
| Endpoint | Purpose |
|---|---|
/api/movements?limit=500 | Fetch movements for vehicle-to-load mapping |
/api/orders/by-ids?ids={ids} | Fetch customer names for order IDs (comma-separated) |
/api/movements/order/{query} | Search for movements by order number |
Metric Filter Definitions
| Filter | Condition | Description |
|---|---|---|
all | No filter | Shows all vehicles |
active | vehicle.driver_id exists | Vehicle has an assigned driver |
inactive | vehicle.driver_id is null/undefined | Vehicle has no assigned driver |
lowFuel | fuel_percentage < 25 | Fuel level below 25% |
UI Layout
LiveVehicleMap.tsx
Interactive Leaflet map component displaying real-time vehicle (tractor) locations with custom markers.Purpose
- Display vehicle locations on an interactive map
- Show vehicle status via color-coded markers (moving/stopped)
- Display detailed vehicle info in popups (driver, load, location, speed, fuel)
- Auto-fit map bounds to show all vehicles
- Support for filtered vehicle display
Props
| Prop | Type | Description |
|---|---|---|
backendUrl | string | Override for tracking backend URL |
className | string | Additional CSS classes |
filteredVehicles | VehicleLocation[] | Vehicles to display (overrides internal data) |
driverIdToNameMap | Map<string, string> | Driver ID to name mapping for popups |
vehicleToLoadMap | Map<string, VehicleActiveLoad> | Vehicle to active load info for popups |
Internal Hook
WhenfilteredVehicles is not provided, the component uses useVehicleLocations() hook internally to fetch and manage vehicle data via SSE.
Default Values
| Setting | Value | Notes |
|---|---|---|
| Default map center | 39.8283, -98.5795 | Geographic center of USA |
| Default zoom | 5 (with vehicles), 4 (empty) | |
| Fit bounds padding | [50, 50] pixels | |
| Fit bounds maxZoom | 10 | Prevents zooming too close |
Unit Conversions
Key Functions
isValidCoordinate
isValidCoordinate
Validates geographic coordinates.
getVehicleStatus
getVehicleStatus
Determines vehicle movement status and marker color.
| Status | Color | Condition |
|---|---|---|
moving | #10b981 (green) | speed > 0 OR engine = “on”/“running” |
stopped | #ef4444 (red) | speed = 0 |
unknown | #3b82f6 (blue) | default |
createVehicleIcon
createVehicleIcon
Creates a Leaflet
divIcon with:- Colored circular background based on status
- Truck SVG icon rotated by heading
- Pulse animation ring for moving vehicles
- White border and shadow
(heading % 360 + 360) % 360This formula normalizes any heading value (including negatives) to 0-359°. The truck SVG points north (up) by default, so heading is applied directly as CSS rotation.handleFitToAll
handleFitToAll
Fits map bounds to show all vehicles with padding.
Popup Content
Vehicle popups display:- Vehicle header (tractor number, provider)
- Driver name (from
driverIdToNameMap) - Active load info (order ID, customer, destination - from
vehicleToLoadMap) - Location (address or coordinates)
- Speed (mph and km/h)
- Heading (degrees)
- Odometer (miles and km)
- Fuel level (percentage)
- Engine state (On/Off with runtime)
- Last update timestamp
Footer Stats
LiveTrailerMap.tsx
Interactive Leaflet map component displaying trailer locations with marker clustering.Purpose
- Display trailer locations on an interactive map
- Cluster trailers when zoomed out for visual clarity
- Show trailer status via color-coded markers (moving/stationary)
- Display detailed trailer info in popups
Props
| Prop | Type | Description |
|---|---|---|
trailers | TrailerLocation[] | Required. Array of trailers to display |
className | string | Additional CSS classes |
Marker Clustering
Usesleaflet.markercluster for clustering with custom configuration:
Cluster Icon
Cluster icons are sized based on child count:| Count | Size | Font Size |
|---|---|---|
| > 100 | 50px | 14px |
| > 50 | 40px | 12px |
| ≤ 50 | 30px | 10px |
#9333ea)
Key Functions
Default Map Center:
39.8283, -98.5795 (geographic center of USA)Safe Handling: The trailers prop defaults to an empty array if undefined is passed.convertTrailerSpeed
convertTrailerSpeed
Converts trailer speed to mph.
getTrailerStatus
getTrailerStatus
Determines trailer movement status based on converted speed.
| Status | Color | Condition |
|---|---|---|
moving | #9333ea (purple) | converted speed > 5 mph |
stationary | #6b7280 (gray) | converted speed ≤ 5 mph or null |
createTrailerIcon
createTrailerIcon
Creates a Leaflet
divIcon with:- Colored circular background based on status
- Package/box SVG icon rotated by heading
- White border and shadow
Popup Content
Trailer popups display:- Trailer ID and provider
- Location (address or coordinates)
- Speed (mph)
- Heading (degrees)
- Status indicator with timestamp
Component Architecture
The component uses a layered architecture because
useMap() hook must be called within a MapContainer child component.ConnectionStatusIndicator.tsx
A compact badge-style component showing SSE connection status with visual feedback.Purpose
- Display real-time SSE connection state
- Provide visual feedback via icons and colors
- Show error messages when connection fails
Props
| Prop | Type | Description |
|---|---|---|
connectionState | SSEConnectionState | Current SSE connection status object |
lastUpdate | string | null | ISO timestamp of last data update (currently unused) |
getStatusConfig
Returns icon, label, badge variant, and styling based on connection status:| Status | Icon | Label | Color |
|---|---|---|---|
connected | Wifi + pulse dot | ”Live” | Green (bg-green-500) |
connecting | Loader2 (spinning) | “Connecting” | Yellow outline |
disconnected | WifiOff | ”Disconnected” | Gray (bg-gray-500) |
error | AlertCircle | ”Error” | Red (bg-red-500) |
Render Output
The
lastUpdate prop is received but currently not displayed in the UI (prefixed with _).ConnectionStatus.tsx
An alternative connection status component with more detailed information including cache status and reconnect functionality.Purpose
- Display SSE connection state with descriptive text
- Show relative time since last update
- Display cache hit/miss status (development only)
- Provide reconnect button on error
Props
| Prop | Type | Description |
|---|---|---|
connectionState | ConnectionState | String literal: 'connected', 'reconnecting', 'error', or other |
lastUpdate | string | null | ISO timestamp of last data update |
cacheStatus | 'hit' | 'miss' | null | Cache status for debugging |
onReconnect | () => void | Callback for reconnect button |
getStatusConfig
| Status | Color | Text | Pulsing |
|---|---|---|---|
connected | Green | ”Live updates active” | Yes |
reconnecting | Yellow | ”Connecting to live updates…” | Yes |
error | Red | ”Live updates unavailable” | No |
| default | Gray | ”Disconnected” | No |
formatLastUpdate
Formats the timestamp as relative time:UI Elements
| Element | Visibility | Description |
|---|---|---|
| Status indicator | Always | Colored dot with optional pulse animation |
| Status text | Always | Descriptive connection state |
| ”Using last known data” | Error state | Fallback indicator |
| Last update time | When available | Relative timestamp |
| Cache status | Dev mode only | Shows HIT/MISS for debugging |
| Reconnect button | Error + callback provided | Manual reconnection trigger |
MapLegend.tsx
A collapsible legend component explaining color codes used in fleet map markers.Purpose
- Explain timing status colors (on-time, early, late, critical)
- Explain motion status indicators (moving vs idle border styles)
- Provide visual example combining both statuses
Props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | '' | Additional CSS classes |
defaultExpanded | boolean | false | Initial expanded state |
Status Definitions
Timing Statuses
| Color | Label | Description |
|---|---|---|
#10b981 (green) | On-Time | Arriving within scheduled window |
#3b82f6 (blue) | Early | Arriving 15+ minutes early |
#f59e0b (amber) | Late | Arriving 30-60 minutes late |
#ef4444 (red) | Critical | Arriving 60+ minutes late |
Motion Statuses
| Border Style | Border Color | Label | Description |
|---|---|---|---|
| Solid | White | Moving | Vehicle in motion (speed > 5mph) |
| Dashed | Gray (#9ca3af) | Idle | Vehicle stationary |
Component Structure
State Management
isExpanded state to toggle visibility of the legend content.
Styling
- Semi-transparent white background with blur (
bg-white/95 backdrop-blur-sm) - Rounded corners with shadow and border
- Smooth hover transition on header
- Compact text sizing (
text-xs,text-sm)

