Logistics Operations Platform

A full-stack Vehicle Route Problem (VRP) optimization platform for logistics and delivery management. This application provides real-time fleet tracking, delivery management, route optimization, and analytics reporting.

Features

Core Modules

• Delivery Management - Create, assign, and track deliveries with priority levels and time windows
• Fleet Management - Manage vehicle registry, maintenance scheduling, and capacity utilization
• Route Optimization - AI-powered route planning using Google OR-Tools for optimal delivery sequences
• Live Tracking - Real-time vehicle location tracking with interactive maps
• Analytics & Reporting - Comprehensive dashboards with KPIs, trends, and performance metrics
• Driver Management - Driver onboarding, shift assignments, and activity monitoring

Key Capabilities

• VRP Solver - Optimizes routes considering vehicle capacity, time windows, and delivery priorities
• CSV Import - Bulk upload deliveries via CSV files for route optimization
• Route Map Visualization - Interactive Leaflet map showing optimized routes with color-coded paths
• Real-time Updates - Track delivery status and vehicle positions live
• Interactive Charts - Visualize performance data with Recharts
• Responsive Design - Modern UI built with React and custom CSS
• RESTful API - FastAPI backend with comprehensive endpoints
• SQLite Database - Lightweight, file-based data persistence

Tech Stack

Frontend

• React 19 - Modern React with TypeScript
• Vite - Fast development and optimized builds
• React Router - Client-side routing
• Recharts - Data visualization charts
• React-Leaflet - Interactive maps
• Lucide React - Icon library

Backend

• FastAPI - High-performance Python web framework
• SQLAlchemy - ORM for database operations
• Google OR-Tools - VRP optimization engine
• Pydantic - Data validation and settings
• Uvicorn - ASGI server

Project Structure

QOD-ROD/
├── backend/
│   ├── app/
│   │   ├── api/routes/      # API endpoints
│   │   ├── core/            # Config & database
│   │   ├── models/          # SQLAlchemy models
│   │   ├── schemas/         # Pydantic schemas
│   │   ├── services/        # Business logic
│   │   │   ├── analytics_service.py
│   │   │   ├── csv_service.py      # CSV upload handling
│   │   │   ├── distance_service.py
│   │   │   └── optimization_service.py
│   │   ├── main.py          # FastAPI app entry
│   │   └── seed.py          # Database seeding
│   ├── requirements.txt     # Python dependencies
│   └── database.db          # SQLite database
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   │   ├── analytics/
│   │   │   ├── common/
│   │   │   ├── dashboard/
│   │   │   ├── deliveries/
│   │   │   ├── fleet/
│   │   │   ├── optimization/
│   │   │   └── tracking/
│   │   ├── pages/           # Page components
│   │   │   ├── Analytics.tsx
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Deliveries.tsx
│   │   │   ├── FleetManagement.tsx
│   │   │   ├── LiveTracking.tsx
│   │   │   └── RouteOptimization.tsx  # With CSV upload & map
│   │   ├── services/        # API client services
│   │   │   ├── analytics.ts
│   │   │   ├── api.ts
│   │   │   ├── csvUpload.ts        # CSV upload service
│   │   │   ├── deliveries.ts
│   │   │   ├── drivers.ts
│   │   │   ├── optimization.ts
│   │   │   ├── tracking.ts
│   │   │   └── vehicles.ts
│   │   ├── types/           # TypeScript types
│   │   ├── App.tsx          # Main app component
│   │   └── main.tsx         # Entry point
│   ├── package.json         # Node dependencies
│   └── index.html           # HTML template
└── README.md

Getting Started

Prerequisites

• Python 3.11 or higher
• Node.js 18 or higher
• npm or yarn

Installation

1. Clone the repository

   git clone <repository-url>
   cd QOD-ROD

2. Set up the Backend

   cd backend
   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate
   
   pip install -r requirements.txt

3. Set up the Frontend

   cd ../frontend
   npm install

Running the Application

1. Start the Backend Server

   cd backend
   uvicorn app.main:app --reload --port 8000

   The API will be available at http://localhost:8000

   • API Documentation: http://localhost:8000/docs
   • Health Check: http://localhost:8000/health

2. Start the Frontend Development Server

   cd frontend
   npm run dev

   The application will be available at http://localhost:5173 (or next available port)

3. Access the Application Open your browser and navigate to the URL shown in the terminal (typically http://localhost:5173)

Default Login

The application includes a default user profile:

• Name: Admin User
• Role: Dispatcher

API Endpoints

Deliveries

• GET /api/v1/deliveries - List all deliveries
• POST /api/v1/deliveries - Create new delivery
• GET /api/v1/deliveries/{id} - Get delivery details
• PUT /api/v1/deliveries/{id}/status - Update delivery status

Vehicles

• GET /api/v1/vehicles - List all vehicles
• POST /api/v1/vehicles - Add new vehicle
• GET /api/v1/vehicles/positions - Get vehicle positions

Drivers

• GET /api/v1/drivers - List all drivers
• POST /api/v1/drivers - Add new driver

Route Optimization

• POST /api/v1/optimization/optimize - Optimize routes for deliveries
• POST /api/v1/optimization/preview - Preview optimization without saving
• POST /api/v1/optimization/upload-csv - Upload deliveries via CSV file
• GET /api/v1/optimization/csv-template - Download CSV template
• POST /api/v1/optimization/optimize-csv - Optimize routes from CSV deliveries
• GET /api/v1/routes - List all routes

Analytics

• GET /api/v1/analytics/dashboard - Dashboard statistics
• GET /api/v1/analytics/weekly-performance - Weekly delivery data
• GET /api/v1/analytics/vehicle-utilization - Fleet utilization metrics
• GET /api/v1/analytics/trends - Delivery trends

Tracking

• GET /api/v1/tracking/vehicles - Real-time vehicle positions

Screenshots

The application includes the following main views:

1. Dashboard - Overview with KPIs, weekly performance chart, and vehicle utilization
2. Live Tracking - Interactive map showing real-time vehicle locations
3. Deliveries - Manage deliveries with filtering and creation modal
4. Route Optimization -
   • Select existing deliveries or upload CSV file
   • AI-powered route optimization with Google OR-Tools
   • Interactive map showing optimized routes with color-coded vehicle paths
   • Route summary with distance, duration, and stops
5. Fleet Management - Manage vehicles and drivers with tabbed interface
6. Analytics - Detailed analytics with trends and status distribution charts

Configuration

Backend CORS

Edit backend/app/main.py to configure allowed origins:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173", "http://localhost:5174"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

API Base URL

Edit frontend/src/services/api.ts to change the backend URL:

const api = axios.create({
  baseURL: 'http://localhost:8000/api/v1',
  headers: {
    'Content-Type': 'application/json',
  },
});

Building for Production

Frontend

cd frontend
npm run build

The production build will be in the dist/ directory.

Backend

The backend can be deployed using any ASGI server:

uvicorn app.main:app --host 0.0.0.0 --port 8000

CSV Upload Feature

The platform supports bulk importing deliveries via CSV files for route optimization.

CSV Format

Required columns:

• customer_name - Customer's full name
• address - Delivery address
• latitude - Latitude coordinate
• longitude - Longitude coordinate
• weight_kg - Package weight in kilograms

Optional columns:

• customer_phone - Contact phone number
• priority - Priority level (low, normal, high, urgent)
• time_window_start - Delivery window start time (HH:MM format)
• time_window_end - Delivery window end time (HH:MM format)

Example CSV

customer_name,customer_phone,address,latitude,longitude,weight_kg,priority,time_window_start,time_window_end
John Doe,555-0100,123 Market St San Francisco CA,37.7849,-122.4094,2.5,normal,09:00,17:00
Jane Smith,555-0101,456 Mission St San Francisco CA,37.7855,-122.4057,3.0,high,10:00,16:00

API Endpoints for CSV

1. Upload CSV - POST /api/v1/optimization/upload-csv

   • Upload a CSV file to parse deliveries
   • Returns parsed deliveries with validation errors if any

2. Download Template - GET /api/v1/optimization/csv-template

   • Download a sample CSV template

3. Optimize CSV Deliveries - POST /api/v1/optimization/optimize-csv

   • Submit parsed CSV deliveries along with vehicle IDs for optimization

Development Notes

Database Seeding

The backend automatically seeds the database with sample data on startup if tables are empty.

Type Safety

• Frontend uses TypeScript with strict type checking
• Backend uses Pydantic for request/response validation

Code Style

• Frontend: ESLint with TypeScript rules
• Backend: Follow PEP 8 guidelines

Dependencies

Backend

• FastAPI >= 0.115.0
• Uvicorn >= 0.27.1
• SQLAlchemy >= 2.0.25
• Pydantic >= 2.10.0
• Google OR-Tools >= 9.12.4544
• Pandas >= 2.1.0

Frontend

• React >= 19.2.0
• React Router DOM >= 7.13.0
• Recharts >= 3.7.0
• React-Leaflet >= 5.0.0
• Axios >= 1.13.5

License

This project is open source and available for personal and commercial use.

Support

For issues or questions, please refer to the API documentation at /docs when the backend is running.

---

Built with React, FastAPI, and Google OR-Tools.