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.

• 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

• 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

• 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 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

• 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

• 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)

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

• 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

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

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
    }

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

# 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

# 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

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

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)

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

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

Built with ❤️ by Ayush Kaneriya