🚛 TransitOps

Smart Transport Operations Platform

A centralized platform to digitize and manage the complete lifecycle of transport operations — from vehicle and driver management to dispatching, maintenance, and expense tracking.

---

📋 Table of Contents

• Objective
• Target Users
• Features
• Tech Stack
• Business Rules
• Database Entities
• Example Workflow
• Setup
• Build Priority

---

🎯 Objective

Replace manual spreadsheets and logbooks with a single system that gives logistics teams real-time visibility into their fleet, enforces business rules automatically, and tracks operational costs end-to-end.

---

👥 Target Users

Role	Icon	Responsibility
Fleet Manager	👨‍💼	Manage vehicles, maintenance, and fleet lifecycle
Dispatcher	📡	Create and dispatch trips, monitor active deliveries
Safety Officer	🛡️	Monitor license validity, driver compliance, safety scores
Financial Analyst	💰	Review fuel, maintenance costs, and vehicle ROI

---

✨ Features

🔐 Authentication

• Secure login using email and password
• Role-Based Access Control (RBAC)
• Registration creates a new organization automatically
• Multi-tenant data isolation via organization_id

📊 Dashboard

• Fleet Manager — KPI cards (Total Vehicles, Active, Available, In Shop), Fleet Utilization %, Pie charts for vehicle & trip status
• Dispatcher — Profile card, My Trips metrics, Trip History table, Trip Status pie chart
• Safety Officer — Profile card, Driver Safety table with license expiry/scores, Active Maintenance, Vehicle Overview
• Financial Analyst — Profile card, Fleet Utilization with links to Finance & Reports

🚗 Vehicle Registry

• Master list with Registration Number (unique), Name, Type, Max Load Capacity, Odometer, Acquisition Cost, Status
• Status values: Available · On Trip · In Shop · Retired
• Full CRUD with org-scoped access

👤 Driver Management

• Profiles: Name, License Number, Category, Expiry Date, Contact, Safety Score, Status
• Status values: Available · On Trip · Off Duty · Suspended
• License expiry highlighting for Safety Officers

📦 Trip Management

• Create trips with source, destination, vehicle, driver, cargo weight, planned distance
• Lifecycle: Draft → Dispatched → Completed → Cancelled
• Fleet Manager can assign trips to Dispatchers

🔧 Maintenance

• Create maintenance records per vehicle
• Vehicle auto-switches to In Shop on active maintenance
• Closing maintenance restores vehicle to Available
• Removed from dispatch selection while in shop

⛽ Fuel & Expense Tracking

• Record fuel logs (liters, cost, date)
• Record other expenses (tolls, maintenance, etc.)
• Auto-compute total operational cost per vehicle

📈 Reports & Analytics

• Fuel Efficiency (Distance / Fuel)
• Fleet Utilization %
• Operational Cost per vehicle
• Vehicle ROI: (Revenue - (Maintenance + Fuel)) / Acquisition Cost
• CSV export

---

🛠 Tech Stack

Layer	Technology
Backend	Express + Sequelize ORM
Frontend	+
Database
Auth	JWT (JSON Web Tokens)
Charts	Recharts

---

📜 Business Rules

Click to expand — 10 mandatory rules

#	Rule
1	Vehicle registration number must be unique
2	Retired or In Shop vehicles must never appear in dispatch selection
3	Drivers with expired licenses or Suspended status cannot be assigned to trips
4	A driver or vehicle already On Trip cannot be assigned to another trip
5	Cargo Weight must not exceed the vehicle's max load capacity
6	Dispatching a trip → vehicle & driver status → On Trip
7	Completing a trip → vehicle & driver status → Available
8	Cancelling a dispatched trip → restores vehicle & driver to Available
9	Creating active maintenance → vehicle status → In Shop
10	Closing maintenance → restores vehicle to Available (unless retired)

---

🗄 Database Entities

Users · Organizations · Vehicles · Drivers · Trips
Maintenance Logs · Fuel Logs · Expenses

Every data entity is scoped by organization_id for multi-tenant isolation.

---

🔄 Example Workflow

1. 🚛 Register vehicle Van-05 (capacity 500 kg)        → Status: Available
2. 👤 Register driver Alex (valid license)              → Status: Available
3. 📦 Create trip (cargo 450 kg ≤ 500 kg)              → Validation passes
4. 🚀 Dispatch trip                                     → Van-05 & Alex → On Trip
5. ✅ Complete trip with final odometer + fuel          → Van-05 & Alex → Available
6. 🔧 Create maintenance (Oil Change)                   → Van-05 → In Shop
7. 🔓 Close maintenance                                 → Van-05 → Available
8. 📊 Reports auto-update cost & fuel efficiency

---

🚀 Setup

Prerequisites

• Node.js v18+ and npm
• MySQL 8+ running

Quick Start

# 1. Clone and install backend
cd backend
npm install
cp .env.example .env          # Configure DB credentials
npx sequelize db:create        # Create database
node server.js                 # Starts on port 5001

# 2. Install and start frontend
cd ../frontend
npm install
npx vite --port 5173           # Starts dev server

Environment Variables

Variable	Default	Description
PORT	5001	Backend server port
DB_HOST	localhost	MySQL host
DB_USER	root	MySQL user
DB_PASS	—	MySQL password
DB_NAME	transitops_db	Database name
JWT_SECRET	—	Secret key for token signing

---

📦 Build Priority

Build order for an 8-hour MVP sprint:

#	Module	Description
1	🔐 Auth & RBAC	Login, roles, org-scoped access control
2	🚗 Vehicle Registry	CRUD, statuses, uniqueness validation
3	👤 Driver Management	Profiles, license validation, statuses
4	📦 Trip Management	Create, dispatch, complete, cancel + auto-transitions
5	📊 Dashboard	Role-specific KPIs, charts
6	🔧 Maintenance	Log creation, auto status → In Shop
7	⛽ Fuel & Expense	Logs, cost computation
8	📈 Reports	Fuel efficiency, ROI, CSV export

---

✅ Deliverables

Status	Deliverable
✅	Responsive web interface
✅	Authentication with RBAC + multi-tenant org isolation
✅	CRUD for Vehicles and Drivers
✅	Trip Management with validations
✅	Automatic status transitions
✅	Maintenance workflow
✅	Fuel & Expense tracking
✅	Dashboard with role-specific KPIs
✅	Charts and visual analytics
✅	Reports with CSV export

---

_{Built with ❤️ for the Odoo Hackathon 2026}