Tracker Hacker - Fleet Management & Dispatch Platform

A sophisticated FastAPI-based fleet management and dispatch system with real-time tracking, intelligent driver matching, and route optimization.

Features

• 🚚 Fleet Management - Manage vehicles, drivers, and trips
• 🗺️ Real-time Tracking - Live vehicle tracking with Leaflet-based visualization
• 🎯 Smart Dispatch - MCDM-based driver ranking with Hours-of-Service (HOS), deadhead, and performance scoring
• 🛣️ Route Optimization - NavPro API integration for intelligent routing
• 📊 Performance Analytics - Track driver performance and fleet metrics
• 🔌 Pluggable ELD - Support for multiple ELD providers (mock, Samsara, Motive)
• 🌙 Modern UI - Dark-themed SPA with intuitive controls

Quick Start

Prerequisites

• Python 3.9+
• pip or uv package manager
• A .env file with NavPro API credentials (see Configuration section)

Installation

1. Clone the repository

   git clone https://github.com/PHANI465/Tracker-Hacker.git
   cd Tracker-Hacker

2. Create .env file from example

   cp .env.example .env

   Then edit .env and add your NavPro API credentials:

   NAVPRO_JWT=your_jwt_token
   NAVPRO_CLIENT_ID=your_client_id
   

3. Install dependencies

   pip install -r truckker/requirements.txt
   # Or with uv:
   uv pip install -r truckker/requirements.txt

4. Run the development server

   bash scripts/run_dev.sh

   Or manually:

   cd truckker
   uvicorn main:app --reload --host 0.0.0.0 --port 8000

5. Access the application

   • 🌐 Web UI: http://localhost:8000
   • 📚 API Docs: http://localhost:8000/docs
   • 💚 Health Check: http://localhost:8000/health

Configuration

Environment Variables

All configuration is managed via the .env file. Copy .env.example as a template:

Variable	Required	Description
NAVPRO_JWT	✅	JWT token for NavPro API authentication
NAVPRO_CLIENT_ID	✅	Client ID for NavPro API
NAVPRO_BASE_URL	⚠️	NavPro API base URL (default: https://api.truckerpath.com/navpro)
NAVPRO_TIMEOUT_SECONDS	⚠️	Request timeout in seconds (default: 10)
ELD_PROVIDER	⚠️	ELD provider type: mock, samsara, or motive (default: mock)
ELD_BASE_URL	Optional	Base URL for ELD provider
ELD_API_KEY	Optional	API key for ELD provider
DATABASE_URL	⚠️	PostgreSQL connection string (default: postgresql://localhost/dispatch)
APP_ENV	⚠️	Environment: development or production (default: development)
DEBUG	⚠️	Enable debug mode: true or false (default: true)

Loading Credentials

The app automatically loads .env on startup and validates critical configuration:

# From config.py
settings = get_settings()  # Automatically validates and logs configuration

If required credentials are missing, you'll see helpful error messages:

======================================================================
⚠️  CONFIGURATION ERRORS:
======================================================================
❌ NAVPRO_JWT is missing. Please set it in your .env file.
❌ NAVPRO_CLIENT_ID is missing. Please set it in your .env file.
======================================================================

API Endpoints

Health Checks

• GET /health - Basic liveness probe

  {
    "status": "healthy",
    "service": "Truckker Fleet Management",
    "version": "1.0.0"
  }

• GET /health/ready - Readiness probe with dependency checks

  {
    "status": "ready",
    "service": "Truckker Fleet Management",
    "version": "1.0.0",
    "config": {
      "navpro_configured": true,
      "eld_provider": "mock",
      "environment": "development"
    }
  }

Fleet Management

• GET /drivers - List all drivers

• GET /drivers/{id} - Get driver details

• POST /drivers - Create new driver

• PUT /drivers/{id} - Update driver

• DELETE /drivers/{id} - Delete driver

• GET /vehicles - List all vehicles

• GET /vehicles/{id} - Get vehicle details

• POST /vehicles - Create new vehicle

• PUT /vehicles/{id} - Update vehicle

Tracking & Dispatch

• GET /tracking - Get real-time tracking data
• GET /tracking/{vehicle_id} - Get vehicle location history
• POST /dispatch - Create dispatch job
• GET /dispatch - List pending dispatches

Routing & Profiles

• GET /routing-profiles - List routing profiles
• POST /routing-profiles - Create custom profile
• GET /terminals - List terminals
• POST /trips - Create trip

Full API documentation available at /docs when running locally.

Development

Project Structure

Tracker-Hacker/
├── truckker/
│   ├── main.py              # FastAPI app entry point
│   ├── config.py            # Configuration management with validation
│   ├── navpro_client.py     # NavPro API client
│   ├── routers/
│   │   ├── drivers.py       # Driver management endpoints
│   │   ├── vehicles.py      # Vehicle management endpoints
│   │   ├── tracking.py      # Real-time tracking endpoints
│   │   ├── trips.py         # Trip management endpoints
│   │   ├── dispatch.py      # Dispatch matching engine
│   │   ├── routing_profiles.py  # Routing profile endpoints
│   │   └── terminals.py     # Terminal management endpoints
│   ├── static/
│   │   ├── index.html       # SPA entry point
│   │   ├── css/            # Stylesheets
│   │   ├── js/             # Frontend JavaScript
│   │   └── images/         # Images and icons
│   └── requirements.txt      # Python dependencies
├── scripts/
│   └── run_dev.sh           # Development startup script
├── .env                      # Environment configuration (create from .env.example)
├── .env.example              # Example environment configuration
├── .gitignore                # Git ignore rules
├── vercel.json              # Vercel deployment configuration
└── README.md                # This file

Adding New Features

1. Create a new router in truckker/routers/
2. Import and register in truckker/main.py:

   from routers import my_feature
   app.include_router(my_feature.router)

3. Use dependency injection for settings:

   from config import get_settings
   
   @router.get("/endpoint")
   async def my_endpoint(settings: Settings = Depends(get_settings)):
       # Your code here

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=truckker

# Run specific test file
pytest tests/test_drivers.py

Deployment

Vercel Deployment

The project includes vercel.json configuration for easy Vercel deployment:

1. Connect your GitHub repository to Vercel
2. Add environment variables in Vercel dashboard:
   • Go to Settings → Environment Variables
   • Add all variables from .env
3. Deploy

   vercel deploy

The app will automatically:

• Install dependencies from requirements.txt
• Run uvicorn on Vercel's Python runtime
• Serve static files from truckker/static/
• Expose health check endpoints for monitoring

Docker Deployment

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY truckker/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY truckker ./truckker
COPY .env .

EXPOSE 8000

CMD ["uvicorn", "truckker.main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t tracker-hacker .
docker run -p 8000:8000 --env-file .env tracker-hacker

Production Configuration

For production deployment, update .env:

APP_ENV=production
DEBUG=false
NAVPRO_TIMEOUT_SECONDS=30

Recommended settings for Vercel:

• Enable "Automatic Deployments" for main branch
• Set up "Preview Deployments" for PR testing
• Configure custom domain in Vercel dashboard

Monitoring & Debugging

Health Checks

# Check if service is alive
curl http://localhost:8000/health

# Check if service is ready for traffic
curl http://localhost:8000/health/ready

Logs

The application logs configuration on startup:

======================================================================
🚀 Truckker Fleet Management - Starting Up
======================================================================
✅ Configuration validated successfully
   NavPro: https://api.truckerpath.com/navpro
   ELD Provider: mock
   Environment: development
✅ All systems ready for operations
======================================================================

API Documentation

FastAPI automatically generates interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Performance Tips

1. Increase NavPro timeout for production:

   NAVPRO_TIMEOUT_SECONDS=30

2. Use connection pooling for database queries

3. Enable caching for frequently accessed data

4. Monitor health endpoints for early error detection

Troubleshooting

Missing Configuration

Error: Configuration validation failed. NAVPRO_JWT is missing.

Solution:

1. Copy .env.example to .env
2. Add your NavPro credentials to .env
3. Restart the application

Port Already in Use

Error: OSError: [Errno 48] Address already in use

Solution:

# Use a different port
cd truckker
uvicorn main:app --reload --port 8001

NavPro API Timeout

Error: NavPro API timed out. Check connectivity or increase NAVPRO_TIMEOUT_SECONDS.

Solution:

NAVPRO_TIMEOUT_SECONDS=30  # Increase from default 10

Database Connection Failed

Error: could not connect to server: Connection refused

Solution:

1. Ensure PostgreSQL is running
2. Check DATABASE_URL in .env
3. Verify database exists:

   createdb dispatch

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and commit: git commit -am 'Add my feature'
4. Push to branch: git push origin feature/my-feature
5. Open a Pull Request

License

MIT License - see LICENSE file for details

Support

For issues or questions:

1. Check the Troubleshooting section
2. Review API docs at /docs endpoint
3. Open an issue on GitHub
4. Contact the development team

Version History

v1.0.0 (Current)

• Initial release
• Fleet management and dispatch system
• Real-time tracking
• NavPro API integration
• Mock ELD provider support

---

Last Updated: April 2026
Status: Active Development
Maintainer: PHANI465