QOD-ROD

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.

Logistics Platform React FastAPI TypeScript Python

Features

Core Modules

Key Capabilities

Tech Stack

Frontend

Backend

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

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:

API Endpoints

Deliveries

Vehicles

Drivers

Route Optimization

Analytics

Tracking

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:

Optional columns:

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

Code Style

Dependencies

Backend

Frontend

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.