An enterprise-grade Transportation Management System (TMS) built for property-carrying commercial vehicle operations. Features automated FMCSA 49 CFR Part 395 compliance calculations, deadhead repositioning routing, an interactive Leaflet route map with truck animation, turn-by-turn navigation instructions, and an SVG 24-Hour Digital ELD Log Sheet with multi-day export.
- 🌐 Live Web Application: https://spotter-ai-tms.vercel.app
- 11-Hour Driving Cap (§395.3(a)(3)): Prevents more than 11 hours of total driving after 10 consecutive hours off duty.
- 14-Hour Consecutive Duty Window (§395.3(a)(2)): Enforces no driving past the 14th consecutive hour after coming on duty.
- 30-Minute Mandatory Rest Break (§395.3(a)(3)(ii)): Schedules a 30-minute off-duty break after 8 cumulative hours of driving.
- 10-Hour Sleeper Berth Reset (§395.3(a)(1)): Automatically resets driving and shift clocks after 10 consecutive hours in Line 1 (Off Duty) or Line 2 (Sleeper Berth).
- 70-Hour / 8-Day Rolling Cycle Limit (§395.3(b)): Tracks and validates cycle consumption against legal limits.
- 1,000-Mile Fueling Stops: Automatically inserts 15-minute Line 4 on-duty fueling stops every 1,000 miles.
- Shipper Loading & Unloading: 1-hour pre-trip inspection and cargo loading at origin (Line 4), and 1-hour unloading at destination (Line 4).
- Origin Pre-Trip Inspection: 15-minute Line 4 inspection prior to deadhead repositioning transit.
- Deadhead Routing Support: Automatically detects when the driver's current position differs from the shipper pickup, calculating deadhead miles separately from loaded freight miles.
- Multi-Stop Commercial Corridor Routing: Powered by OSRM/Valhalla commercial truck routing with geodesic Haversine fallbacks.
- Truck Restriction Checks: Verified against Interstate standard clearances (13'6" height, 80,000 lbs Gross Vehicle Weight).
- Turn-by-Turn Maneuver Instructions: Real-time navigation step instructions with maneuver icons, highway names, leg-type milestone alerts, and duration.
- Animated Truck Traversal: Moves a custom semi-truck marker along the route geometry with variable playback speed (1x, 2x, 5x, 10x).
- Floating HUD Telemetry: Displays current duty status, simulated speed (55 mph), odometer progression, and dynamic countdowns to the next mandatory rest or fuel stop.
- Synchronized Route Highlighting: Selecting any Day tab highlights the specific route geometry traveled on that day.
- Smart Waypoint Flags: Interactive markers for Pickup, Dropoff, 30-min Meal Breaks, 10-hr Sleeper Berth resets, and Fuel Stops.
- Stepped Duty Polyline: 96-increment resolution (15 minutes per slice) across the 4 official FMCSA duty lines:
- Line 1: Off Duty
- Line 2: Sleeper Berth
- Line 3: Driving
- Line 4: On Duty (Not Driving)
- Midnight Boundary Splitter: Mathematically guarantees the 24.0-hour daily total invariant across multi-day trips by cleanly splitting continuous overnight events at 00:00 midnight.
- Official FMCSA §395.8 Header Fields: Carrier name, DOT number, Driver name & ID, Co-driver, B/L number, Trailer number, and Home Terminal.
- Multi-Day PDF Export / Print: One-click multi-day export producing print-ready, audit-compliant ELD driver daily logs.
spotter-tms/
├── api/ # Vercel Serverless WSGI Entrypoint
│ └── index.py # Python 3.12 WSGI handler
├── backend/ # Django Backend
│ ├── hos_engine/ # HOS Core Application
│ │ ├── services/
│ │ │ ├── hos_simulator.py # Chronological HOS state machine
│ │ │ ├── midnight_splitter.py# 24-hr calendar day event partitioner
│ │ │ └── routing_service.py # Commercial truck routing & geocoding
│ │ ├── serializers.py # Request validation serializers
│ │ ├── views.py # REST API endpoints
│ │ ├── urls.py # URL dispatchers
│ │ └── tests/ # Automated test suite
│ ├── tms_core/ # Django project configuration
│ └── manage.py
├── frontend/ # React Frontend (Vite)
│ ├── src/
│ │ ├── components/
│ │ │ ├── RouteMap.jsx # Leaflet map with animated truck & HUD
│ │ │ ├── EldLogSheet.jsx # SVG 24-hour ELD log sheet & export
│ │ │ ├── RouteInstructions.jsx# Step-by-step turn maneuvers
│ │ │ ├── TripForm.jsx # Location & cycle input panel
│ │ │ ├── TripSummaryCard.jsx# Telemetry metrics display
│ │ │ └── DayTabs.jsx # Multi-day navigation tabs
│ │ ├── App.jsx # Main layout and state orchestrator
│ │ └── index.css # Cyber-sleek dark SaaS styling
│ └── package.json
├── vercel.json # Vercel deployment configuration
└── requirements.txt # Backend Python dependencies
- Python 3.11+
- Node.js 18+ & npm
# Clone the repository
git clone https://github.com/affan004/spotter-tms.git
cd spotter-tms/backend
# Create and activate virtual environment
python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# Install dependencies
pip install -r ../requirements.txt
# Run migrations and start server
python manage.py migrate
python manage.py runserver 127.0.0.1:8000cd ../frontend
# Install npm dependencies
npm install
# Start development server
npm run devVisit http://localhost:5173 in your browser.
The project includes unit and integration tests verifying all FMCSA regulations and boundary conditions:
cd backend
python manage.py testtest_11_hour_driving_limit: Enforces 10-hour sleeper berth when driving cap is reached.test_14_hour_duty_window: Enforces rest when on-duty duration hits 14 consecutive hours.test_30_minute_mandatory_rest_break: Validates meal break after 8 hours of cumulative driving.test_70_hour_cycle_limit_detection: Triggers cycle limit alert when 70 hours are exceeded.test_fuel_stop_every_1000_miles: Verifies 15-minute Line 4 stops at 1,000-mile intervals.test_midnight_splitter_24_hour_invariant: Proves exact 24.0 hours accounted on every single day.test_deadhead_repositioning_routing: Ensures separate origin inspection and deadhead tracking.test_calculate_trip_api_endpoint: Validates HTTP 200 JSON payload structure.test_sample_trips_api_endpoint: Verifies pre-configured demo routes.
Calculates full commercial truck route, HOS simulation timeline, turn-by-turn maneuvers, and daily ELD sheets.
Payload:
{
"current_location": "Indianapolis, IN",
"pickup_location": "Indianapolis, IN",
"dropoff_location": "Dallas, TX",
"current_cycle_used": 14.5,
"avg_speed": 55.0,
"start_time": "2026-09-28T08:00:00",
"truck_height_ft": 13.5,
"truck_weight_lbs": 80000.0
}Returns pre-configured demonstration routes (Midwest to Texas, Chicago to Atlanta, Cross-Country Coast).
MIT License. Built for the Spotter.ai TMS assessment.