🚌 Campus Bus Tracking & Booking System

A hybrid real-time transportation management system for campuses — combining live GPS tracking, seat reservation, e-ticket generation, and multi-role dashboards for students, drivers, and transport officers.

---

📋 Table of Contents

• Overview
• Architecture
• Features by Role
• Tech Stack
• Dual Tracking Architecture
• Activity Flow
• Getting Started
• Project Structure
• Environment Variables
• Deployment
• Contributing

---

🌐 Overview

The Campus Bus Tracking & Booking System enables smooth coordination among students, drivers, and the Transport Officer (Admin). It provides:

• 🗺️ Live GPS bus tracking via WebSocket
• 🎟️ Real-time seat booking with e-ticket generation
• 🔔 In-app notifications from admin to students/drivers
• 📊 Admin fleet management with occupancy metrics
• 🔐 Role-based access control (Student / Driver / Admin)

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │   Student    │  │    Driver    │  │  Admin / T.O.    │  │
│  │  Dashboard   │  │  Dashboard   │  │    Dashboard     │  │
│  │  (React SPA) │  │  (React SPA) │  │   (React SPA)   │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
└─────────┼─────────────────┼───────────────────┼────────────┘
          │                 │                   │
          │   WebSocket (STOMP/SockJS)           │
          │                 │                   │
┌─────────▼─────────────────▼───────────────────▼────────────┐
│                      BACKEND LAYER                          │
│              Spring Boot 3.5.6  |  Java 21                  │
│         WebSocketController  │  REST Controllers            │
│              Thymeleaf (Map Views)                          │
│                    Port: 5000                               │
└──────────────────────────┬──────────────────────────────────┘
                           │
          ┌────────────────┴────────────────┐
          │                                 │
┌─────────▼──────────┐           ┌──────────▼──────────┐
│   Firebase Auth    │           │   Cloud Firestore   │
│  (User Management) │           │  (NoSQL Database)   │
│                    │           │  Real-time listeners│
└────────────────────┘           └─────────────────────┘

System Type

Hybrid Real-Time Transportation Management System combining:

• Real-time GPS tracking (WebSocket-based)
• Seat booking/reservation system (Firebase-based)
• Multi-role access control (Student / Driver / Admin)

---

👥 Features by Role

🎓 Student Dashboard

Feature	Description
🚌 Track Buses	View all "Available" buses on a live map with real-time driver GPS
🎟️ Book Ride	Browse routes, view 17-seater layout, choose seat, and confirm booking
📄 My Tickets	View upcoming/past bookings; tickets auto-expire on bus departure
🔔 Notifications	Receive admin messages (delays, cancellations, schedule changes)

Booking Flow:

1. Browse available buses → select route
2. View seat layout (17-seater) → choose an unoccupied seat
3. Confirm booking → e-ticket generated with seat number, Bus ID, driver details
4. Track live bus location until departure

---

🚍 Driver Dashboard

Feature	Description
▶️ Start/End Journey	Enter Bus ID & Driver Name to begin; mark as "Completed" when done
📍 GPS Tracking	Continuously broadcasts real-time coordinates to server
🗺️ Route Visualization	Live map with current position and route path
⏸️ Journey Controls	Pause/resume tracking for breaks; shows GPS accuracy

---

🧑‍💼 Admin / Transport Officer Dashboard

Feature	Description
🗺️ Live Tracking	Monitor all active buses: Bus ID, route, driver, occupancy
📊 Fleet Metrics	Total buses, active buses, total passengers onboard
✅ Availability Control	Mark buses "Available" (opens booking) or "Departed" (closes booking, frees seats)
➕ Manual Bus Entry	Add buses with ID, route, driver, and seating capacity
💬 Notifications	Broadcast messages to all students or specific drivers

---

🛠️ Tech Stack

Backend

Technology	Version	Purpose
Java	21	Core language
Spring Boot	3.5.6	Application framework
WebSocket (STOMP/SockJS)	—	Real-time bidirectional communication
Thymeleaf	—	Server-side map view rendering
Maven	—	Dependency management

Frontend

Technology	Version	Purpose
React	18.3	UI framework
TypeScript	5.x	Type safety
Vite	—	Build tool
React Router	v6	Client-side routing
TanStack Query	—	Server state management
shadcn/ui + Radix UI	—	Component library
Tailwind CSS	—	Styling with custom campus theme
Leaflet.js	—	Interactive maps

Database & Auth

Technology	Purpose
Firebase Authentication	User management & login
Cloud Firestore	NoSQL data persistence + real-time listeners

---

🔄 Dual Tracking Architecture

The system uses two complementary tracking mechanisms:

A. WebSocket Tracking (Backend-Driven)

For real-time GPS broadcasting

Driver Browser → GPS Capture (every 5s)
     ↓
WebSocket: /app/location → WebSocketController
     ↓
Broadcast: /topic/location
     ↓
Map Viewers (/mapbtw) → Live Markers Updated

Key features:

• Auto-reconnection on disconnect
• Heartbeat mechanism (25s intervals, ngrok-compatible)
• Marker cleanup for inactive users (after 5 minutes)
• Multi-bus tracking with unique identifiers
• No authentication required (open system)

B. Firebase Tracking (Frontend-Driven)

For booking management and bus status

Admin marks bus "Available" → Firestore update
     ↓
Students see available buses via real-time listeners
     ↓
Student books seat → occupancy increments
     ↓
Admin marks "Departed" → all bookings expire, seats reset

Key features:

• Role-based access control
• Real-time data synchronization
• Optimistic UI updates
• Offline capability via Firebase SDK

---

🗺️ Activity Flow

The full activity diagram (see below) illustrates the end-to-end flow across all four actors:

Student → Admin/T.O. → Driver → System (Server/Database)

Summarized flow:

1. Student opens dashboard → views available buses → books a seat → receives e-ticket
2. Admin monitors bus status → marks arrival/departure → sends notifications
3. Driver starts journey → sends live GPS → ends journey → notifies admin
4. System receives GPS data → updates Firestore → broadcasts to all dashboards → enforces booking rules

---

🚀 Getting Started

Prerequisites

• Java 21 or higher
• Maven 3.6+ (included via Maven wrapper)
• Node.js 18+ and npm
• Firebase Account (for authentication and database)
• ngrok (optional, for external WebSocket access)

1. Clone the Repository

git clone https://github.com/MAHESHPPAI/Busbuddy-latest.git
cd Busbuddy-latest

2. Backend Setup

cd Backend

# Install dependencies and run (using Maven wrapper)
./mvnw clean install
./mvnw spring-boot:run

# Or on Windows
mvnw.cmd clean install
mvnw.cmd spring-boot:run

# Backend will start on http://localhost:5000

3. Frontend Setup

cd Frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Frontend will start on http://localhost:5173 (default Vite port)

📁 Project Structure

Busbuddy-latest/
├── Backend/                          # Spring Boot application
│   ├── src/main/java/com/sivapa08/livetrackingsystem/
│   │   ├── controller/
│   │   │   ├── APIController.java
│   │   │   └── WebSocketController.java
│   │   ├── socket/
│   │   │   └── Endpoints.java        # WebSocket configuration
│   │   ├── util/
│   │   │   └── LocationDetails.java  # Location data model
│   │   └── LivetrackingsystemApplication.java
│   ├── src/main/resources/
│   │   ├── templates/
│   │   │   ├── index.html            # Driver tracking interface
│   │   │   └── map.html              # Live map viewer
│   │   └── application.properties
│   ├── mvnw / mvnw.cmd               # Maven wrapper
│   └── pom.xml
│
├── Frontend/                         # React SPA
│   ├── src/
│   │   ├── components/
│   │   │   ├── StudentDashboard.tsx
│   │   │   ├── DriverDashboard.tsx
│   │   │   ├── AdminDashboard.tsx
│   │   │   ├── BusTrackingMap.tsx    # Embedded map component
│   │   │   ├── SeatBookingPage.tsx   # Seat selection UI
│   │   │   ├── MyTicketsPage.tsx     # Ticket management
│   │   │   └── ui/                   # shadcn/ui components
│   │   ├── lib/
│   │   │   ├── firebase.ts           # Firebase config
│   │   │   ├── firestore.ts          # Database operations
│   │   │   ├── auth.ts               # Authentication helpers
│   │   │   ├── notifications.ts      # Notification system
│   │   │   └── pdfGenerator.ts       # E-ticket PDF generation
│   │   ├── pages/
│   │   │   ├── Index.tsx             # Landing page
│   │   │   └── NotFound.tsx
│   │   └── App.tsx
│   ├── firestore.rules               # Firestore security rules
## 🔐 Environment Variables

### Backend — `Backend/src/main/resources/application.properties`
```properties
# Server Configuration
server.port=5000

# ngrok compatibility
server.forward-headers-strategy=framework

# WebSocket Configuration
spring.websocket.allowed-origins=*

# Logging (optional - for debugging)
logging.level.org.springframework.web.socket=DEBUG
logging.level.org.springframework.messaging=DEBUG

Frontend — Firebase Configuration

Update Frontend/src/lib/firebase.ts with your Firebase project credentials:

const firebaseConfig = {
## ☁️ Deployment

### Backend Deployment (Railway / Render / Heroku)
```bash
cd Backend
./mvnw clean package -DskipTests
# Deploy the generated JAR file from target/livetrackingsystem-0.0.1-SNAPSHOT.jar

Frontend Deployment (Vercel / Netlify / Lovable)

cd Frontend
npm run build
# Deploy the dist/ folder

Firebase Setup

1. Enable Firestore in Firebase Console
2. Enable Authentication with Email/Password provider
3. Deploy security rules from Frontend/firestore.rules
4. Add production domain to Firebase Auth authorized domains
5. Create collections: admins, drivers (manually add authorized users)

ngrok for Development

ngrok http 5000
# Update ngrok URL in:
# - Frontend/src/components/BusTrackingMap.tsx
# - Frontend/src/components/DriverDashboard.tsx

└── README.md

---

## 🔐 Environment Variables

### Backend — `application.properties`
```properties
server.port=5000
firebase.credentials.path=classpath:firebase-service-account.json
ngrok.enabled=true

Frontend — .env

VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_WEBSOCKET_URL=http://localhost:5000

---

☁️ Deployment

Backend (e.g., Railway / Render)

mvn clean package -DskipTests
java -jar target/campus-bus-tracking-*.jar

Frontend (e.g., Vercel / Netlify)

npm run build
# Deploy the dist/ folder

Firebase

• Enable Firestore and Authentication (Email/Password) in Firebase Console
• Set Firestore security rules to enforce role-based access
• Add your production domain to Firebase Auth authorized domains

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature/your-feature-name
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Built with ❤️ for smarter campus mobility