🚚 TransitOps

Smart Transport Operations Platform

Digitize vehicle, driver, dispatch, maintenance, and expense management — with business rules enforced at the API layer and full operational visibility through dashboards and reports.

Built for Odoo Hackathon 2026.

---

Overview

Many logistics teams still run on spreadsheets and manual logbooks, leading to scheduling conflicts, underused vehicles, missed maintenance, expired licenses, and poor cost visibility. TransitOps centralizes the entire transport lifecycle in one platform and enforces the rules that keep operations safe and consistent.

Features

• Authentication & RBAC — JWT login with four roles, enforced on both the API and the UI (role-based menus).
• Vehicle registry — full CRUD with unique registration numbers, capacity, odometer, and lifecycle status.
• Driver management — license validity tracking, safety scores, and status.
• Trip dispatch — create → dispatch → complete/cancel, with a full status timeline and live eligibility checks.
• Maintenance workflow — opening/closing records automatically syncs vehicle availability.
• Fuel & expense tracking — per-vehicle operational cost.
• Dashboard & reports — fleet utilization, fuel efficiency, operational cost, and vehicle ROI, with CSV export.

Monorepo Structure

TransitOps/
├── backend/     # FastAPI + SQLAlchemy API on local PostgreSQL
├── frontend/    # React 19 + TanStack Router + Vite + Tailwind + shadcn/ui
└── README.md

Each part has its own README with setup instructions:

• backend/README.md — API, database, and business rules
• frontend/ — the web client

Architecture

┌──────────────┐        HTTP / JWT        ┌──────────────┐        SQL        ┌───────────────┐
│   Frontend   │  ───────────────────▶    │   FastAPI    │  ──────────────▶  │  PostgreSQL   │
│  React/Vite  │  ◀───────────────────    │   Backend    │  ◀──────────────  │   (pgAdmin4)  │
└──────────────┘         JSON             └──────────────┘                   └───────────────┘

• Frontend — React 19, TanStack Router, Vite 8, Tailwind CSS 4, shadcn/ui, Recharts.
• Backend — FastAPI, SQLAlchemy, JWT auth, role-based access control, transactional business rules.
• Database — local PostgreSQL 18, managed with pgAdmin4.

Roles (RBAC)

Role	Responsibilities
Fleet Manager	Full access to vehicles, maintenance, and vehicle lifecycle.
Driver	Creates trips and monitors assigned deliveries.
Safety Officer	Manages driver compliance, license validity, safety scores.
Financial Analyst	Manages expenses, fuel logs, and reports.

Quick Start

Backend

cd backend
cp .env.example .env          # set your local Postgres password/port
python -m pip install -r requirements.txt
python seed.py                # create tables + demo data
python -m uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
bun install
bun run dev                   # http://localhost:8080

Demo Accounts

Password for all: Demo1234!

Role	Email
Fleet Manager	manager@transitops.demo
Driver	driver@transitops.demo
Safety Officer	safety@transitops.demo
Financial Analyst	finance@transitops.demo

Business Rules (enforced server-side, transactionally)

1. Vehicle registration numbers are unique.
2. Retired or in-shop vehicles never appear in dispatch selection.
3. Drivers with expired licenses or suspended status cannot be assigned to trips.
4. A vehicle or driver already on a trip cannot be double-booked.
5. Cargo weight cannot exceed the vehicle's maximum load capacity.
6. Dispatching a trip sets vehicle and driver to On Trip.
7. Completing a trip restores both to Available and records odometer + fuel used.
8. Cancelling a dispatched trip restores vehicle and driver to Available.
9. Opening an active maintenance record sets the vehicle to In Shop.
10. Closing maintenance restores the vehicle to Available (unless retired).

Demo Flow

1. Sign in as Fleet Manager (manager@transitops.demo / Demo1234!).
2. Open Trips — each row shows its assigned vehicle and driver.
3. New trip — only available vehicles and valid-license drivers are listed; cargo over capacity is blocked inline.
4. Dispatch a draft trip → the vehicle and driver flip to On Trip.
5. Complete the trip (enter odometer + fuel) → both return to Available.
6. Maintenance — open a record → vehicle becomes In Shop; close it → back to Available.
7. Explore Reports (fuel efficiency, operational cost, ROI, CSV export) and sign in as other roles to see role-based access.

Roadmap

• Local PostgreSQL schema + FastAPI backend (auth, RBAC, CRUD, business rules)
• Demo data seeding
• React frontend (dashboard, vehicles, drivers, trips, maintenance, fuel, expenses, reports)
• Frontend wired to the FastAPI backend with JWT auth
• Optional: PDF export, license-expiry email reminders, dark mode

License

Built for the Odoo Hackathon 2026.