🚛 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.

🎯 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

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
    }

⚖️ 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 --> [*]

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 --> [*]

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 --> [*]

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

📄 License

Built for hackathon submission purposes.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
server		server
src		src
.gitignore		.gitignore
Readme.md		Readme.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js

Folders and files

Latest commit

History

Repository files navigation

🚛 TransitOps — Smart Transport Operations Platform

📑 Table of Contents

🎯 Problem Statement

🚀 Key Features

Role-Based Access Control (RBAC)

Trip Lifecycle Management

Live Fleet Tracking

Fleet & Driver Management

Maintenance & Expense Tracking

Real-Time Analytics & Reporting

🏗 System Architecture

🗃 Database Schema

⚖️ Business Rules & State Machines

Trip Lifecycle

Vehicle Status

Driver Status

Enforced Validation Rules

💻 Tech Stack

Frontend

Backend

🛠 Getting Started

Prerequisites

1. Installation

2. Environment Setup

3. Database Seeding

4. Run the Application

🔐 Demo Accounts

📂 Project Structure

🔌 API Overview

🎁 Roadmap / Bonus Features

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages