TransitOps — Smart Transport Operations Platform

Enterprise-ready logistics, fleet management, and driver compliance engine
Enforce load safety rules, driver license checks, and atomic state updates inside a secure split-monolith

---

Table of Contents

• Overview
• Why TransitOps
• Key Features
• Architecture
• Pipeline Flow and How It Works
• User Interface Guide
• Default Seed Credentials
• Project Documentation Guides
• Quick Start
• Troubleshooting
• Author

---

Overview

TransitOps is a modern transport and fleet management system built to digitize and automate logistics workflows. It coordinates vehicle scheduling, compliance audits, fuel consumption records, and driver logs while enforcing strict safety thresholds and multi-role operations.

By combining a decoupled React frontend and a TypeScript Express API powered by Prisma and MySQL, the system provides high performance, audit safety, and role-based guardrails.

---

Why TransitOps

Traditional fleet tracking relies on separate spreadsheets, paper logs, and manual checklist checks, resulting in overloaded vehicles, expired licenses, and double-booking. TransitOps replaces these offline workflows with an integrated, compliance-enforced digital platform.

Scenario / Hazard	Spreadsheets and Manual Logs	TransitOps Solution
Expired License Check	Relies on manual audit; drivers with expired licenses can easily be assigned.	Automated Blocker: Enforces license verification at the API layer, blocking dispatch if expired.
Vehicle Overloading	Weight limits are estimated; cargo load is checked manually.	Payload Enforcement: Compares cargo weight against vehicle capacity and blocks overloaded dispatches.
Scheduling Conflicts	High risk of double-booking vehicles and drivers.	Atomic Dispatch: Updates driver and vehicle states to OnTrip atomically in a database transaction.
Maintenance Control	Vehicles are verbally marked "in shop" but can still be scheduled.	Maintenance Block: Putting a vehicle in maintenance sets its state to InShop and hides it from selection lists.
Financial Accounting	Fuel logs and tolls are calculated separately in accounting software.	Completion Cascade: Trip completion automatically records fuel usage and toll expenses in a database cascade.

---

Key Features

🚦 Driver Compliance Engine

• Active Validity: Checks driver licenses during dispatch. Expired licenses are blocked from assignments.
• Amber and Red Warnings: Emphasizes expiration dates in the frontend UI (Amber within 30 days, Red when expired).
• Driver State Lock: Suspended or off-duty staff are filtered out of the allocation lists.

⚖️ Payload Enforcement

• Capacity Auditing: Blocks trip creation if the cargo weight exceeds the maximum capacity of the vehicle.

⚡ Atomic Cascade Transactions

• Atomic Dispatch: Dispatching a trip updates both the vehicle and driver status to OnTrip inside a secure MySQL transaction.
• Trip Completion Cascade: Transitions the trip to Completed, updates the vehicle odometer, logs fuel costs, records toll/other expenses, and returns the vehicle and driver to Available atomically.
• Trip Cancellation: Restores vehicle and driver status back to Available in a single transaction.

🔧 Maintenance Management

• In-Shop Blocks: Logging a vehicle repair ticket automatically changes its status to InShop, hiding it from active dispatch lists.
• Service Release: Completing the service restores the vehicle to Available status.

🛡️ Brute Force Failsafe

• Accounts are locked out for 30 minutes after 5 consecutive failed login attempts to protect against credentials cracking.

---

Architecture

TransitOps is organized as a split-monolith where the client UI and REST API backend share a MySQL database synchronized via Prisma.

graph TD
    User["Client Browser"] -->|Vite Dev Server / Nginx| Frontend["React Frontend (Zustand + React Router v6)"]
    Frontend -->|HTTP Requests / Auth Header| API["Express REST API (TypeScript)"]
    API -->|Auth Middleware / JWT| Guards["RBAC Guard Rails"]
    Guards -->|ORM Query| Prisma["Prisma Client"]
    Prisma -->|Transaction / Lock| DB[("MySQL Database")]
    API -->|Email Dispatch| Resend["Resend API / SMTP"]

Loading

ASCII fallback (click to expand)

  ┌────────────────────────────────────────────────────────┐
  │                    Client Browser                      │
  └──────────────────────────┬─────────────────────────────┘
                             │ (Vite Dev Server / Nginx)
                             ▼
  ┌────────────────────────────────────────────────────────┐
  │          React Frontend (Zustand + React Router v6)    │
  └──────────────────────────┬─────────────────────────────┘
                             │ (HTTP Requests + JWT Auth Header)
                             ▼
  ┌────────────────────────────────────────────────────────┐
  │              Express REST API (TypeScript)             │
  └──────────────────────────┬─────────────────────────────┘
                             │ (Auth Middleware)
                             ▼
  ┌────────────────────────────────────────────────────────┐
  │                 RBAC Guard Rails                       │
  └──────────────────────────┬─────────────────────────────┘
                             │ (Prisma Client)
                             ▼
  ┌──────────────────────────┴─────────────────────────────┐
  │                 MySQL Database                         │
  └────────────────────────────────────────────────────────┘

---

Pipeline Flow and How It Works

Trip Dispatch and Completion Pipeline

flowchart TD
    A["Create Trip (Draft)\nEnforces cargo weight <= capacity"] --> B["Dispatch Trip\nAtomic transaction starts"]
    B --> C["Driver and Vehicle set to OnTrip\nTrip set to Dispatched"]
    C --> D["Complete Trip\nUser enters odometer, fuel, and expenses"]
    D --> E["Atomic completion cascade starts"]
    E --> F["Vehicle odometer updated\nFuel log created\nExpense log created"]
    F --> G["Driver and Vehicle released to Available\nTrip status set to Completed"]

Loading

ASCII fallback (click to expand)

[Create Trip (Draft)]
         │ (Enforces cargo weight <= vehicle capacity)
         ▼
[Dispatch Trip]
         │ (Atomic transaction updates statuses)
         ▼
[Driver and Vehicle set to 'OnTrip' & Trip set to 'Dispatched']
         │
         ▼
[Complete Trip]
         │ (User enters final odometer, fuel, and expenses)
         ▼
[Atomic Completion Cascade]
         │ (Odometer updated + Fuel log created + Expense log created)
         ▼
[Driver and Vehicle set to 'Available' & Trip status set to 'Completed']

---

User Interface Guide

The frontend features a responsive layout matching system permissions.

View / Page	Key Visual Panels	Permitted Interactions
Dashboard	KPI Cards (Utilization, Active/Pending Trips, Available Drivers, Active Vehicles) and Recent Trips table.	- View real-time operations. - View vehicle status distribution chart.
Fleet Registry	Vehicle details cards (Model, Odometer, Reg Number, Capacity, Status Badge).	- Full CRUD (Fleet Manager only). - Read-only details view (Dispatcher and Safety Officer).
Driver Registry	Staff registry (License category, license expiry warnings: Amber $\le 30$ days, Red $\le 0$ days).	- Full CRUD (Fleet Manager and Safety Officer). - Read-only compliance audit (Dispatcher).
Trip Management	Pipeline dispatch boards showing Draft, Dispatched, Completed, and Cancelled columns.	- Create, Dispatch, Cancel, and Complete trips (Dispatcher and Fleet Manager only).
Maintenance Log	active maintenance logs, vehicle in-shop list.	- Open and Close tickets (Fleet Manager and Safety Officer). - Read-only service view (Dispatcher and Financial Analyst).
Fuel and Expenses	Fuel Fill-ups and Expense logs tables.	- Log fuel usage and miscellaneous costs (Financial Analyst). - View cost reports (Fleet Manager).
Analytics	Monthly revenue charts and Fleet ROI breakdown.	- View operational reports and export data to CSV (Fleet Manager and Financial Analyst only).
Settings	Depot name, Currency, and Distance Unit forms.	- Update global configurations (Fleet Manager only).

---

Default Seed Credentials

Seed data is initialized via npx ts-node prisma/seed.ts.

Role	Email	Password	Allowed Sidebar Scope
Fleet Manager	admin@transitops.com	admin123	Full access across all configuration panels, registries, trips, and reports.
Fleet Manager (Backup)	manager2@transitops.com	password123	Backup administrator account.
Dispatcher	dispatcher@transitops.com	password123	Create and dispatch trips; read-only fleet/maintenance views.
Safety Officer	safety@transitops.com	password123	Manage driver details, check compliance, and open/close maintenance logs.
Financial Analyst	finance@transitops.com	password123	Log and view expenses, fuel efficiency, and ROI reports.

---

Project Documentation Guides

Refer to these dedicated documents in the documentation/ directory for detailed business and architectural references:

• 📑 Logistics Business Rules — Weight limits and status override rules.
• 🔐 RBAC Matrix — User authorization and route guard permissions.
• 🔑 Default Seed Credentials — Login accounts and safety timeout policies.
• ⚙️ API Reference — Full REST API query, parameter, and response maps.
• 🧪 Verification Checklist — Setup and logs for Jest and Vitest test suites.

---

Quick Start

1. Backend Setup

cd backend
npm install
cp .env.example .env
# Edit .env and fill in your MySQL DATABASE_URL, then run:
npx prisma migrate dev --name initial
npx ts-node prisma/seed.ts
npm run dev

2. Frontend Setup

cd ../frontend
npm install
cp .env.example .env
npm run dev

---

Troubleshooting

Problem	Cause	Solution
Prisma migration error	MySQL service not running or database does not exist.	Ensure MySQL is running on port 3306 and matches the DATABASE_URL credentials in backend/.env.
Trip dispatch blocked	Target vehicle is InShop / OnTrip or driver's license is expired.	Verify driver compliance dates and choose a vehicle marked Available.
401 Unauthorized	JWT token expired or missing.	Clear browser local storage or log out and log back in to renew your token.
Account locked out	5 failed login attempts exceeded.	Wait 30 minutes for the lock to release, or manually reset the user database entry.

---

Author

Felix-au (Harshit Soni)

• 🔗 GitHub: github.com/Felix-au
• 📧 Email: felixaugum@gmail.com

---

_{Seamlessly orchestrating logistics with intelligence and compliance safety.}