Public Transportation Management System

An IoT-integrated web application for real-time bus tracking, schedule and route management, RFID-based contactless fare payment, and seat booking—built with the MERN stack, Socket.io, Stripe, and ESP32.

---

Features

Route & Schedule Management

• Bus stops – Create, edit, and manage bus stops with map integration
• Routes – Define routes with stop sequences and distance calculation
• Schedules – Set bus departure times and frequencies per route
• Buses – Manage fleet with bus details, capacity, and assignments

Real-Time Tracking

• Live bus location tracking via Google Maps
• Interactive map views for routes, stops, and bus positions
• Socket.io-based real-time updates

Booking & Seats

• Search buses by route, date, and time
• Interactive seat layout for booking
• View and manage passenger bookings (My Bookings)

Payment & Cards

• Smart cards – NFC/RFID-based contactless payment simulation
• Visa cards – Card-based payment integration
• Stripe – Online payment processing for top-ups
• Fare calculation based on distance
• Top-up, recharge, refund, and transaction history

User & Admin

• Role-based access (Admin, Passenger)
• User registration and authentication (JWT)
• Forgot password & password reset
• User management (CRUD) for admins
• Passenger profile and account settings

Notifications & Reports

• Email notifications (welcome, password reset, account changes)
• Revenue dashboard and reporting
• Transaction history with export (PDF via jsPDF)

---

Tech Stack

Layer	Technology
Frontend	React 19, React Router, Axios
Backend	Node.js, Express 5
Database	MongoDB (Mongoose)
Maps	@react-google-maps/api
Real-time	Socket.io
Payments	Stripe
Auth	JWT, bcrypt
Email	Nodemailer
IoT	ESP32 (RFID/NFC integration)

---

Project Structure

├── backend/
│   ├── controllers/       # Auth, cards, payments, revenue, transactions
│   ├── models/            # User, Booking, Route, Bus, Schedule, Payment, etc.
│   ├── routes/            # API endpoints
│   ├── services/          # Email service
│   ├── utils/             # Auth, mailer, fare calculator, etc.
│   └── server.js          # Express + Socket.io entry point
│
├── frontend/
│   ├── public/
│   └── src/
│       ├── components/    # Auth, RouteManagement, payments, dashboards
│       ├── contexts/      # AuthContext
│       ├── services/      # API client
│       └── styles/        # CSS modules
│
└── docs/                  # README_AUTH, EMAIL_SYSTEM_DOCUMENTATION, etc.

---

Prerequisites

• Node.js 18+
• MongoDB (local or Atlas)
• Google Maps API key (for map features)
• Stripe account (optional, for real payments)

---

Installation

1. Clone the repository

git clone https://github.com/vikumfernando/Public-Transportation-Management-System.git
cd Public-Transportation-Management-System

2. Backend setup

cd backend
npm install

Create a .env file in backend/:

# MongoDB
MONGODB_URL=mongodb://localhost:27017/transportation
# or: mongodb+srv://user:pass@cluster.mongodb.net/transportation

# Server
PORT=8070

# JWT
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=7d

# Stripe (optional – app runs in demo mode without)
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

# Email (optional – for notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
MAIL_FROM=your-email@gmail.com
FRONTEND_URL=http://localhost:3000

# Client (for password reset links)
CLIENT_URL=http://localhost:3000

3. Seed admin user (optional)

npm run seed-admin

4. Frontend setup

cd ../frontend
npm install

Create .env in frontend/ if needed:

REACT_APP_API_URL=http://localhost:8070
REACT_APP_GOOGLE_MAPS_API_KEY=your_google_maps_api_key

---

Running the Application

Development

Terminal 1 – Backend:

cd backend
npm run dev
# Server: http://localhost:8070

Terminal 2 – Frontend:

cd frontend
npm start
# App: http://localhost:3000

Production

# Build frontend
cd frontend && npm run build

# Run backend (serves API; serve frontend build with nginx/similar)
cd backend && npm start

---

API Overview

Route Prefix	Description
/auth	Sign up, sign in, password reset
/users	User CRUD, profile
/Stops	Bus stops
/Busses	Buses
/Routes	Routes
/Schedules	Schedules
/Bookings	Seat bookings
/BusSearch	Search buses
/api	Cards, payments, transactions
/api/revenue	Revenue reports

---

Documentation

• README_AUTH.md – Authentication and sign-in/sign-up
• README_USER_MANAGEMENT.md – User management
• EMAIL_SYSTEM_DOCUMENTATION.md – Email notifications
• USER_MANAGEMENT_TEST_GUIDE.md – Testing guide

---

Authors

• Vikum Fernando
• Nethshan Dulmin
• Tharindu Nethmal
• Saliya Buwaneka

---

License

ISC