🚛 TransitOps — Smart Transport Operations Platform

A centralized, end-to-end fleet management system that digitizes vehicle dispatch, driver compliance, maintenance workflows, and operational analytics — replacing spreadsheets and paper logbooks.

Built in an 8-hour hackathon sprint, TransitOps manages the complete lifecycle of transport operations: from vehicle registration and driver onboarding to trip dispatch, maintenance scheduling, and fuel/expense tracking — all with strict, automated business-rule enforcement.

---

📑 Table of Contents

• Problem Statement
• Key Features
• System Architecture
• Database Schema
• Business Rules & State Machines
• Tech Stack
• Getting Started
• Demo Accounts
• Project Structure
• API Overview
• Roadmap

---

🎯 Problem Statement

Logistics companies often run transport operations on spreadsheets and manual logbooks, leading to:

• Scheduling conflicts (double-booked vehicles/drivers)
• Underutilized vehicles with no visibility into fleet performance
• Missed maintenance windows and expired driver licenses going unnoticed
• Inaccurate expense and fuel-cost tracking
• Zero real-time operational visibility for decision-makers

TransitOps solves this by centralizing the entire fleet lifecycle behind a single, rule-enforced platform with role-specific access for Fleet Managers, Dispatchers, Safety Officers, and Financial Analysts.

---

🚀 Key Features

Role-Based Access Control (RBAC)

Role	Access
Fleet Manager	Full access — vehicles, drivers, maintenance schedules
Dispatcher	Create, dispatch, and track trips
Financial Analyst	Fuel logs, operational expenses, cost analytics
Safety Officer	Read-only oversight — license validity, safety scores, compliance

Trip Lifecycle Management

• Full lifecycle: Draft → Dispatched → Completed / Cancelled
• Cargo weight validated against vehicle capacity before dispatch
• Vehicle/driver auto-locked to prevent double-assignment

Live Fleet Tracking

• Interactive map view of active trips and vehicle locations (Leaflet)

Fleet & Driver Management

• Vehicle registry — type, capacity, odometer, acquisition cost, status
• Driver profiles — license validity, safety score, availability

Maintenance & Expense Tracking

• Maintenance logs automatically lock a vehicle out of dispatch
• Fuel, tolls, and repair costs tracked with validation

Real-Time Analytics & Reporting

• Fleet utilization, cost, and ROI dashboards (Recharts)
• Export to CSV / PDF

---

🏗 System Architecture

flowchart LR
    subgraph Client["🖥️ React Frontend (Vite)"]
        A[Dashboard]
        B[Vehicle Registry]
        C[Driver Management]
        D[Trip Management]
        E[Maintenance & Fuel]
        F[Reports & Analytics]
    end

    subgraph Server["⚙️ Express.js Backend"]
        G[JWT Auth Middleware]
        H[RBAC Middleware]
        I[API Routes]
        J[Business Rule Engine]
    end

    subgraph Data["🗄️ SQLite Database"]
        K[(transitops.db)]
    end

    Client -->|Axios / REST API| G
    G --> H
    H --> I
    I --> J
    J --> K
    K --> J
    J --> I
    I -->|JSON Response| Client

Loading

Flow: every request is authenticated via JWT, checked against the caller's role, then passed through the business-rule engine (status validation, conflict checks) before touching the database.

---

🗃 Database Schema

erDiagram
    ROLES ||--o{ USERS : has
    USERS ||--o{ TRIPS : creates
    VEHICLES ||--o{ TRIPS : assigned_to
    DRIVERS ||--o{ TRIPS : assigned_to
    VEHICLES ||--o{ MAINTENANCE_LOGS : undergoes
    VEHICLES ||--o{ FUEL_LOGS : logs
    TRIPS ||--o{ EXPENSES : incurs
    VEHICLES ||--o{ EXPENSES : incurs

    ROLES {
        int id PK
        string name
    }
    USERS {
        int id PK
        string email
        string password_hash
        int role_id FK
    }
    VEHICLES {
        int id PK
        string registration_number UK
        string name_model
        string type
        float max_load_capacity
        float odometer
        float acquisition_cost
        string status
    }
    DRIVERS {
        int id PK
        string name
        string license_number
        string license_category
        date license_expiry
        string contact_number
        int safety_score
        string status
    }
    TRIPS {
        int id PK
        string source
        string destination
        int vehicle_id FK
        int driver_id FK
        float cargo_weight
        float planned_distance
        float fuel_consumed
        float final_odometer
        string status
        int created_by FK
    }
    MAINTENANCE_LOGS {
        int id PK
        int vehicle_id FK
        string description
        float cost
        date date
        string status
    }
    FUEL_LOGS {
        int id PK
        int vehicle_id FK
        float liters
        float cost
        date date
    }
    EXPENSES {
        int id PK
        int trip_id FK
        int vehicle_id FK
        string type
        float amount
        date date
    }

Loading

---

⚖️ Business Rules & State Machines

Status transitions for Vehicles, Drivers, and Trips are tightly coupled — dispatching or completing a trip cascades status changes across all three.

Trip Lifecycle

stateDiagram-v2
    [*] --> Draft
    Draft --> Dispatched : dispatch()\n(validates cargo, availability)
    Dispatched --> Completed : complete()\n(enter odometer + fuel)
    Dispatched --> Cancelled : cancel()
    Completed --> [*]
    Cancelled --> [*]

Loading

Vehicle Status

stateDiagram-v2
    [*] --> Available
    Available --> OnTrip : trip dispatched
    OnTrip --> Available : trip completed / cancelled
    Available --> InShop : maintenance record created
    InShop --> Available : maintenance closed (not retired)
    Available --> Retired : retire()
    Retired --> [*]

Loading

Driver Status

stateDiagram-v2
    [*] --> Available
    Available --> OnTrip : trip dispatched
    OnTrip --> Available : trip completed / cancelled
    Available --> OffDuty : off_duty()
    OffDuty --> Available : back_on_duty()
    Available --> Suspended : suspend()\n(license expired / violation)
    Suspended --> [*]

Loading

Enforced Validation Rules

Rule	Enforced At
Registration number must be unique	Vehicle creation
Retired / In Shop vehicles never appear in dispatch selection	Trip creation
Drivers with expired license or Suspended status cannot be assigned	Trip creation
A vehicle/driver already On Trip cannot be assigned to another trip	Trip creation
Cargo weight must not exceed vehicle's max load capacity	Trip creation
Dispatch → vehicle and driver flip to On Trip	Trip dispatch
Complete → vehicle and driver revert to Available	Trip completion
Cancel (dispatched trip) → vehicle and driver revert to Available	Trip cancellation
Active maintenance record → vehicle flips to In Shop	Maintenance creation
Closing maintenance → vehicle reverts to Available (unless retired)	Maintenance closure

---

💻 Tech Stack

Frontend

Layer	Technology
Framework	React 18 (Vite)
Routing	React Router v6
Styling	Custom vanilla CSS — dark-mode glassmorphism
Charts	Recharts
Maps	Leaflet + React-Leaflet
Icons	Lucide React

Backend

Layer	Technology
Runtime	Node.js
API Framework	Express.js
Database	SQLite3 (better-sqlite3)
Auth	JWT + bcryptjs
Reporting	jspdf, jspdf-autotable, json2csv

---

🛠 Getting Started

Prerequisites

• Node.js v20 LTS
• npm or yarn

1. Installation

npm install

2. Environment Setup

Create a .env file in the root directory:

PORT=3001
JWT_SECRET=your_super_secret_key_here
DB_PATH=./data/transitops.db
SESSION_EXPIRY=24h

3. Database Seeding

Initializes schema and populates demo data (users, vehicles, trips):

npm run seed

4. Run the Application

Starts frontend and backend concurrently:

npm run dev

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:3001

---

🔐 Demo Accounts

Password for all accounts: Transit@2026

Role	Email
Fleet Manager	fleet@transitops.in
Dispatcher	dispatch@transitops.in
Safety Officer	safety@transitops.in
Financial Analyst	finance@transitops.in

---

📂 Project Structure

├── server/
│   ├── config/        # Database setup and connection
│   ├── middleware/    # Auth and RBAC middleware
│   ├── routes/        # Express API endpoints
│   ├── index.js       # Main server entry point
│   └── seed.js        # Database seeding script
├── src/
│   ├── components/    # Reusable UI components
│   ├── context/       # React Context (Auth)
│   ├── pages/         # Application views (Dashboard, Login, Fleet, etc.)
│   ├── utils/         # Axios API interceptors and helpers
│   ├── App.jsx        # React Router configuration
│   └── main.jsx        # React DOM rendering
├── data/               # SQLite database storage (git-ignored)
└── package.json        # Project dependencies and scripts

---

🔌 API Overview

Method	Endpoint	Description	Roles
POST	/api/auth/login	Authenticate user, returns JWT	All
GET	/api/vehicles	List vehicles (filterable)	All
POST	/api/vehicles	Register a vehicle	Fleet Manager
GET	/api/drivers	List drivers	All
POST	/api/drivers	Register a driver	Fleet Manager
POST	/api/trips	Create a trip (Draft)	Dispatcher
POST	/api/trips/:id/dispatch	Dispatch a trip	Dispatcher
POST	/api/trips/:id/complete	Complete a trip	Dispatcher
POST	/api/trips/:id/cancel	Cancel a trip	Dispatcher
POST	/api/maintenance	Log maintenance	Fleet Manager
PATCH	/api/maintenance/:id/close	Close maintenance record	Fleet Manager
POST	/api/fuel-logs	Record fuel log	Fleet Manager / Financial Analyst
POST	/api/expenses	Record expense	Financial Analyst
GET	/api/reports/utilization	Fleet utilization report	Fleet Manager / Financial Analyst
GET	/api/reports/roi	Vehicle ROI report	Financial Analyst
GET	/api/dashboard/kpis	Dashboard KPI summary	All

---

🎁 Roadmap / Bonus Features

• Responsive web interface
• Authentication with RBAC
• CRUD for Vehicles and Drivers
• Trip management with full validation
• Automatic status transitions
• Maintenance workflow
• Fuel & expense tracking
• Dashboard with KPIs
• Charts and visual analytics
• CSV export
• PDF export
• Email reminders for expiring licenses
• Vehicle document management
• Advanced search, filters, and sorting
• Dark mode toggle

---

📄 License

Built for hackathon submission purposes.