TransitOps — Smart Transport Operations Platform

Full-stack fleet management platform built in 8 hours
React 19 · FastAPI · PostgreSQL · MinIO · Docker

---

Features

Fleet Management

• Vehicle Registry — CRUD with type, status, capacity, acquisition cost, and odometer tracking
• Driver Registry — License management with expiry dates, safety scores, and compliance status
• Driver-User Linking — Assign Driver-role users to driver profiles for trip dispatching

Trip Operations & Route Planning

• Trip Lifecycle — Plan → Confirm → Dispatch → Complete/Cancel with full state machine
• TollGuru Route Planning — 2–3 route options with distance, toll cost, fuel estimate, and polyline
• Interactive Route Map — Leaflet + OpenStreetMap with TollGuru polylines rendered on trip planning
• Automatic Status Transitions — Dispatch → On Trip, Complete → Available, Cancel → Available
• Business Rule Enforcement — Capacity checks, compliance gates, license expiry blocks, double-assignment prevention

Maintenance

• Maintenance Workflow — Auto "In Shop" on create, auto "Available" on close
• Per-Vehicle Tracking — Service type, cost, entry/exit dates, status

Fuel & Expense Tracking

• Fuel Logs — Per-vehicle fuel entries with liters and cost
• Expense Records — Toll, other costs, total cost per trip/vehicle
• Document Management — MinIO-powered upload/download/delete for bills and licenses

Dashboard & Analytics

• 7 Real-Time KPIs — Fleet utilization, on-time delivery, safety incidents, total trips, fuel efficiency, operational cost, vehicle ROI
• Interactive Charts — Bar charts, donut charts, line charts, cost breakdowns via Recharts
• Date Range & Filter Support — Vehicle type, status, and date range filtering

PDF & CSV Export

• Branded PDF Export — 3-page report with canvas-rendered bar/donut/line charts, KPI cards, auto-tables, page numbers
• CSV Export — Multi-section CSV with all analytics data

AI Chatbot

• Ask TransitOps — Google Gemini-powered floating chat widget for fleet queries in natural language

Email Notifications

• Driver License Reminders — SendGrid-powered automated alerts for licenses expiring within 30 days

Internationalization

• English + Hindi — Full UI translation toggle via i18next (161 translation keys)

Theme

• Dark Mode — System-wide light/dark toggle with localStorage persistence

Demo Data

• One-Click Seed — Admin Settings page seeds 20 vehicles, 12 drivers, 40 trips, 60+ fuel logs, 40+ expenses, and 20+ maintenance records
• 8 Pre-Configured Users — All roles ready to demo

Access Control

• 6 Roles — Fleet Manager, Dispatcher, Driver, Safety Officer, Financial Analyst, Admin
• Admin Superuser — Bypasses all RBAC checks
• Per-Endpoint Permissions — Backend enforces role-based access on every API route

---

PRD Deliverables — All Implemented

Mandatory Requirements

#	Requirement	Implementation
1	Responsive web interface	Tailwind CSS, mobile-friendly grid layouts
2	Authentication with RBAC	JWT login, 6 roles, per-endpoint permissions, Admin superuser
3	CRUD for Vehicles & Drivers	Full create/read/update/delete with validation
4	Trip Management with validations	Capacity checks, compliance gates, license expiry blocks
5	Automatic status transitions	Dispatch → On Trip, Complete → Available, Cancel → Available
6	Maintenance workflow	Auto In Shop on create, auto Available on close
7	Fuel & Expense tracking	Per-vehicle fuel logs + expense records with MinIO uploads
8	Dashboard with KPIs	7 real-time KPIs computed from live database
9	Charts and visual analytics	Bar charts, donut charts, line charts, cost breakdowns
10	PDF export	3-page branded PDF with canvas-rendered charts

Bonus Features

#	Feature	Implementation
11	Email reminders for expiring licenses	SendGrid integration, HTML emails, 30-day threshold
12	Vehicle document management	MinIO upload/download/delete for bills and licenses
13	Search, filters, and sorting	Vehicle type/status/search, driver status, date range filters
14	Dark mode	System-wide light/dark toggle with localStorage persistence

---

Business Rules

Every rule from the PRD is enforced server-side:

Rule	Enforcement Point
Vehicle registration number must be unique	POST /api/fleet/vehicles — 400 on duplicate
Retired/In Shop vehicles excluded from dispatch	PUT /trips/{id}/dispatch — status check
Expired license blocks dispatch	PUT /trips/{id}/dispatch — expiry_date < today
Suspended drivers blocked from dispatch	PUT /trips/{id}/dispatch — status check
On Trip vehicle/driver cannot be double-assigned	PUT /trips/{id}/dispatch — availability check
Cargo weight ≤ vehicle capacity	POST /trips/plan + PUT /trips/{id}/dispatch — 422 on breach
Dispatch auto-sets On Trip	PUT /trips/{id}/dispatch — transactional state mutation
Complete auto-sets Available	PUT /trips/{id}/complete — frees both assets
Cancel restores Available	PUT /trips/{id}/cancel — frees both assets if Dispatched
Maintenance auto-sets In Shop	POST /operations/maintenance — vehicle status mutation
Close maintenance restores Available	PUT /maintenance/{id}/complete — vehicle status restore
Admin bypasses all RBAC	require_roles() — checks RoleName.ADMIN first

---

RBAC Matrix

Action	Fleet Mgr	Dispatcher	Driver	Safety	Finance	Admin
Vehicle CRUD	✅	❌	❌	❌	❌	✅
Driver CRUD	✅	❌	❌	✅	❌	✅
Create Trip	❌	✅	❌	❌	❌	✅
Plan Routes	❌	✅	✅	❌	❌	✅
Dispatch Trip	❌	✅	❌	❌	❌	✅
Complete Trip	❌	✅	✅	❌	❌	✅
Maintenance CRUD	✅	❌	❌	❌	❌	✅
Fuel Logs	❌	❌	❌	❌	✅	✅
Expenses	❌	❌	❌	❌	✅	✅
Analytics	✅	✅	✅	✅	✅	✅
Admin (all)	✅	✅	✅	✅	✅	✅

---

Tech Stack

Layer	Technology
Frontend	React 19, Vite 8, TypeScript 6
Styling	Tailwind CSS 4, shadcn/ui
Charts	Recharts 3.9
Export	jsPDF, jspdf-autotable, PapaParse
i18n	i18next, react-i18next
Backend	FastAPI 0.139, Python 3.11
ORM	SQLModel, SQLAlchemy 2.0
Database	PostgreSQL 16 (asyncpg)
Auth	PyJWT (HS256), bcrypt
Storage	MinIO (S3-compatible)
AI	Google Gemini
Routing	TollGuru API
Email	SendGrid API
Maps	Leaflet + OpenStreetMap
Infra	Docker Compose

---

API Endpoints

29 REST endpoints across 8 modules:

Module	Prefix	Endpoints	Description
Authentication	/api/auth	5	Login, register, roles, seed
Fleet	/api/fleet	9	Vehicle + Driver CRUD
Operations	/api/operations	10	Trip lifecycle + Maintenance
Finance	/api/finance	6	Fuel logs + Expenses
Analytics	/api/analytics	1	Dashboard KPI aggregation
Documents	/api/documents	3	MinIO file upload/download/delete
Chat	/api/chat	1	Gemini AI assistant
Admin	/api/admin	1	Database seed (Admin-only)

Swagger UI: http://localhost:8000/docs

---

Dashboard KPIs

All computed in real-time from the database:

KPI	Calculation
Fleet Utilization	(vehicles ON_TRIP / total) × 100
On-Time Delivery	(completed trips / total trips) × 100
Safety Incidents	Count of SUSPENDED drivers
Total Trips	COUNT(*) from trips table
Avg Fuel Efficiency	SUM(odometer) / SUM(liters)
Operational Cost	SUM(fuel_cost) + SUM(maintenance_cost) + SUM(toll_cost)
Vehicle ROI	(Revenue - (Maint + Fuel)) / AcqCost × 100

---

Database Schema

8 tables with foreign keys, check constraints, and enum types:

roles ──< users >── drivers ──< trips >──< expenses >── maintenance_logs
                            │                              │
                        vehicles ──< fuel_logs             │
                                  ──< expenses ────────────┘

Table	Key Constraints
roles	UNIQUE name (enum: 6 roles)
users	UNIQUE email, FK → roles
vehicles	UNIQUE reg_no, CHECK capacity > 0
drivers	UNIQUE license_no, CHECK score 0–100
trips	UNIQUE trip_code, FK → vehicles/drivers
maintenance_logs	FK → vehicles
fuel_logs	FK → vehicles, CHECK liters > 0
expenses	FK → vehicles/trips/maintenance

---

Quick Start

Prerequisites

• Docker & Docker Compose

Run

git clone https://github.com/Abhinav-kodes/TransitOps.git
cd TransitOps
docker compose up -d --build

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
MinIO Console	http://localhost:9001

Demo Credentials

Role	Email	Password
Admin	admin@transitops.com	admin123
Fleet Manager	fleet@transitops.com	fleet123
Dispatcher	dispatch@transitops.com	dispatch123
Driver	driver@transitops.com	driver123
Safety Officer	safety@transitops.com	safety123
Financial Analyst	finance@transitops.com	finance123

After login as Admin, go to Settings → click Seed Demo Data to populate the dashboard with sample trips, vehicles, drivers, and expenses.

---

Project Structure

odoo/
├── docker-compose.yml
├── backend/
│   ├── main.py
│   ├── api/
│   │   ├── dependencies.py
│   │   ├── authentication/
│   │   ├── fleet/
│   │   ├── operations/
│   │   ├── finance/
│   │   ├── analytics/
│   │   ├── documents/
│   │   ├── chat/
│   │   └── admin/
│   └── packages/db/models/
├── frontend/
│   ├── src/
│   │   ├── App.tsx
│   │   ├── lib/
│   │   ├── pages/
│   │   ├── components/dashboard/
│   │   └── locales/
│   └── public/
└── docs/
    └── ARCHITECTURE.md

---

What Makes This Stand Out

1. Every PRD requirement implemented — mandatory + bonus, zero shortcuts
2. 14 extra features beyond PRD — AI chatbot, interactive maps, Hindi i18n, branded PDF export, email notifications
3. All business rules enforced server-side — no client-side-only validation
4. Real-time analytics — every KPI from live database queries
5. Professional PDF export — canvas-rendered charts in a branded 3-page report
6. One-click demo data seeding — 20 vehicles, 12 drivers, 40 trips in one button press
7. 8 database tables with proper constraints and foreign keys
8. 29 REST endpoints with per-endpoint RBAC
9. Full i18n — 161 translation keys in English and Hindi
10. Built in 8 hours — full-stack, containerized, documented

---

MIT License. Built for hackathon evaluation.