🚛 FleetFlow — Modular Fleet & Logistics Management System

FleetFlow is a full-stack fleet management system built with Django. It provides real-time visibility into vehicle operations, driver management, trip dispatching, expense tracking, and operational analytics — all through a polished, responsive web interface with HTMX-powered interactions.

---

✨ Key Features

🎯 Command Center (Dashboard)

• Real-time KPI cards: Total Fleet, Available, On Trip, In Maintenance
• Vehicle type & region filters with pending cargo tracking
• Recent activity feed with status-coded trip history

🚗 Vehicle Registry

• Full vehicle lifecycle management (Available → On Trip → In Shop → Retired)
• Track name, license plate, type (Truck / Van / Bike), capacity, odometer, acquisition cost, and region
• Modal-based create/edit forms with inline validation
• Retire/reactivate vehicles with audit logging

📋 Trip Dispatch & Management

• Draft → Dispatched → Completed / Cancelled lifecycle
• Create trips with vehicle, driver, origin, destination, cargo weight, and revenue
• Save-time validation: vehicle/driver availability, cargo capacity, license validity, vehicle–driver category matching
• Edit draft trips; dispatch with instant toast error feedback
• Complete trips with odometer end reading
• HTMX-powered inline row updates without page reload

👨‍✈️ Driver Safety & Compliance

• Driver profiles with license tracking and expiry warnings (30-day alert)
• Vehicle category certification (Truck / Van / Bike / All)
• Safety score tracking and trip completion rate metrics
• Status management: Available, On Trip, Off Duty, Suspended
• Detail pages with trip history

💰 Expenses & Fuel Tracking

• Log fuel, toll, and other expenses linked to vehicles and trips
• Vehicle–trip mismatch validation (ensures expense vehicle matches trip vehicle)
• Three-tab interface:
  • Expense Log — all expenses with category filter
  • Completed Trips — recent completed trips summary
  • Vehicle Costs — per-vehicle fuel and maintenance cost breakdown

📊 Operational Analytics

• All metrics respect vehicle type and region filters
• Overview tab:
  • 4 primary KPIs: Utilization, Revenue, Ops Cost, Net Profit
  • 4 secondary metrics: Trips, KM Driven, Avg km/L, Vehicles
  • Revenue vs. Cost stacked bar chart per vehicle
  • Fleet composition breakdown by vehicle type
  • Top 5 Revenue Generators and Most Profitable Vehicles tables
• Vehicle Performance tab:
  • Per-vehicle table with distance, fuel, efficiency, revenue, costs, profit, and ROI
  • Color-coded fuel efficiency and ROI indicators
• CSV export (restricted to Manager / Analyst roles)

🔐 Role-Based Access Control (RBAC)

Role	Permissions
Fleet Manager	Full access: create, edit, dispatch, retire, manage drivers, export data
Dispatcher	Create/edit trips, log expenses, dispatch vehicles
Safety Officer	Manage drivers, log maintenance records
Financial Analyst	View analytics, export CSV reports

• Server-side enforcement via @role_required decorator
• UI-level enforcement: action buttons hidden based on user role

🛡️ Maintenance & Service Logs

• Log maintenance records (Oil Change, Tire Rotation, Brake Service, Engine Repair, Inspection, Other)
• Vehicles auto-transition to In Shop status when maintenance is logged
• Resolve maintenance records; vehicle returns to Available when all records resolved
• Filter by resolved/unresolved status

---

🏗️ Architecture

Tech Stack

Layer	Technology
Backend	Django 5.1, Python 3.12
Database	PostgreSQL 16
Frontend	HTMX 1.19, Tailwind CSS (CDN), native <dialog> modals
Serving	Gunicorn, WhiteNoise (static files)
Containerization	Docker, Docker Compose

Project Structure

fleetflow/
├── accounts/          # Custom User model, auth views, RBAC roles
├── core/              # Dashboard, audit trail, decorators, management commands
├── fleet/             # Vehicle & Maintenance models, views, forms
├── drivers/           # Driver model, compliance tracking, status management
├── operations/        # Trip model, dispatch/complete/cancel services
├── finance/           # Expense model, fuel tracking, cost analysis
├── analytics/         # Analytics dashboard, CSV export, data visualizations
├── templates/         # Django templates (base, partials, modals)
│   ├── base.html      # Global layout, sidebar, modal system, tab/toast JS
│   ├── core/          # Dashboard template
│   ├── operations/    # Trip list, detail, form, row partials
│   ├── fleet/         # Vehicle & maintenance templates
│   ├── drivers/       # Driver templates
│   ├── finance/       # Expense templates (tabbed)
│   ├── analytics/     # Analytics dashboard (tabbed)
│   └── accounts/      # Login, register, password reset
├── static/            # Static assets
├── fleetflow/         # Django project settings, URLs, WSGI
├── Dockerfile         # Production container
├── docker-compose.yml # Dev environment (PostgreSQL + Django)
└── requirements.txt   # Python dependencies

Data Model (ER Diagram)

erDiagram
    User ||--o{ Trip : creates
    User {
        string username
        string role
        string phone
    }
    Vehicle ||--o{ Trip : assigned_to
    Vehicle ||--o{ Expense : incurs
    Vehicle ||--o{ Maintenance : has
    Vehicle {
        string name
        string license_plate
        string vehicle_type
        decimal capacity
        decimal odometer
        string region
        string status
    }
    Driver ||--o{ Trip : drives
    Driver {
        string name
        string license_number
        date license_expiry
        string vehicle_category
        decimal safety_score
        string status
    }
    Trip ||--o{ Expense : generates
    Trip {
        string origin
        string destination
        decimal cargo_weight
        decimal revenue
        string status
        decimal odometer_start
        decimal odometer_end
    }
    Expense {
        string category
        decimal cost
        decimal liters
        date date
    }
    Maintenance {
        string service_type
        decimal cost
        date date
        boolean is_resolved
    }

Loading

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• PostgreSQL 14+ (or use Docker)
• pip or pipenv

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/ayushkaneriya05/FleetFlow.git
cd FleetFlow

# Start PostgreSQL + Django
docker compose up --build

# In another terminal, run migrations and create a superuser
docker compose exec web python manage.py migrate
docker compose exec web python manage.py createsuperuser

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

Option 2: Local Development

# Clone the repository
git clone https://github.com/ayushkaneriya05/FleetFlow.git
cd FleetFlow

# 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

# Set up PostgreSQL database
# Create a database named 'fleetflow' in PostgreSQL

# Configure environment variables (create .env file)
echo 'export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/fleetflow"' > .env

# Run migrations
python manage.py migrate

# Create a superuser
python manage.py createsuperuser

# Start the development server
python manage.py runserver

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

Environment Variables

Variable	Default	Description
DATABASE_URL	—	PostgreSQL connection string (takes priority)
DB_NAME	fleetflow	Database name (fallback)
DB_USER	postgres	Database user (fallback)
DB_PASSWORD	postgres	Database password (fallback)
DB_HOST	localhost	Database host (fallback)
DB_PORT	5432	Database port (fallback)
DJANGO_SECRET_KEY	dev key	Secret key (change in production!)
DJANGO_DEBUG	True	Debug mode
ALLOWED_HOSTS	localhost,127.0.0.1	Comma-separated allowed hosts

---

🧪 Usage

Creating Your First Fleet

1. Register/Login — Create an account with the Fleet Manager role
2. Add Vehicles — Go to Vehicle Registry → Add Vehicle (name, plate, type, capacity, region)
3. Add Drivers — Go to Driver Safety → Add Driver (name, license, category, expiry)
4. Create a Trip — Go to Trip Dispatch → Create Trip (select vehicle, driver, route, cargo)
5. Dispatch — Click the Dispatch button on a Draft trip (validates availability and capacity)
6. Complete — Click Complete, enter odometer end reading
7. Log Expenses — Go to Expenses & Fuel → Log Expense (link to vehicle and trip)
8. View Analytics — Go to Analytics for revenue, costs, fleet utilization, and per-vehicle ROI

HTMX Interactions

FleetFlow uses HTMX for a seamless single-page-like experience:

• Modal forms — All create/edit operations open in a native <dialog> modal loaded via HTMX
• Inline updates — Dispatch, cancel, and status changes update the table row in-place
• Toast notifications — Success/error messages appear as floating toasts via HX-Trigger headers
• Tab navigation — Client-side tabs for multi-section pages (Finance, Analytics)

---

📦 Dependencies

Package	Version	Purpose
Django	≥5.1	Web framework
psycopg2-binary	≥2.9	PostgreSQL adapter
django-htmx	≥1.19	HTMX middleware and utilities
django-widget-tweaks	≥1.5	Template form rendering helpers
whitenoise	≥6.7	Static file serving in production
gunicorn	≥23.0	Production WSGI server
WeasyPrint	≥62.0	PDF report generation

---

🤝 Contributing

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

---

📄 License

This project is open source and available under the MIT License.

---

Built with ❤️ by Ayush Kaneriya