🚍 Shuttle Tracker

A real-time bus tracking and pick-up notification system built for NST students.

---

✨ Overview

The Shuttle Tracker web-app allows students to:

• 📍 See the exact location of their college shuttle
• 🛎️ Request a pick-up with one tap
• 🗓️ Display their class schedule to the driver

This system reduces confusion and unnecessary calls, helping everyone stay on time.

🎯 Impact

Role	Benefits
Students	Shorter waiting times, on-time arrivals
Drivers	Fewer calls, clearer routing
Faculty	Fewer class disruptions
NST Management	More disciplined, data-driven transport system

---

🚀 Tech Stack

• Frontend: React 19, Vite, TailwindCSS
• Backend: Node.js, Express.js, Socket.io
• Authentication: Google OAuth, JWT
• Real-time Communication: Socket.io
• Maps: Leaflet, React-Leaflet

---

📂 Project Structure

Shuttle_Tracker/
├── backend/                 # Node.js backend server
│   ├── src/
│   │   ├── app.js          # Express app entry point
│   │   ├── socket.js       # Socket.io configuration
│   │   ├── models/         # Database models
│   │   │   └── Bus.js      # Bus model schema
│   │   └── routes/         # API route handlers
│   │       ├── auth.js     # Authentication routes
│   │       └── bus.js      # Bus tracking routes
│   ├── package.json        # Backend dependencies
│   └── .env.example        # Environment variables template
│
├── frontend/               # React frontend application
│   └── src/
│       ├── App.jsx         # Main React component
│       ├── main.jsx        # React entry point
│       ├── socket.js       # Socket.io client setup
│       ├── components/     # Reusable UI components
│       │   ├── BusCard.jsx
│       │   ├── Footer.jsx
│       │   ├── Loader.jsx
│       │   ├── Navbar.jsx
│       │   ├── ThemeProvider.jsx
│       │   └── ThemeToggle.jsx
│       ├── pages/          # Application pages/views
│       │   ├── Driver.jsx
│       │   ├── Home.jsx
│       │   ├── Student.jsx
│       │   └── TrackShuttle.jsx
│       └── assets/logo/main-logo.png
│       ├── index.html      # HTML template
│       ├── package.json    # Frontend dependencies
│       ├── vite.config.js  # Vite configuration
│       ├── tailwind.config.js # TailwindCSS config
│       └── eslint.config.js   # ESLint configuration
│
├── README.md               # Project documentation (this file)
├── HLD.md                  # High-level design document
└── LICENSE                 # MIT license

---

🤝 Contributing Guide

We welcome contributions from the community!

🚦 Quick Start

1. Fork & Clone

git clone https://github.com/YOUR_USERNAME/Shuttle_Tracker.git
cd Shuttle_Tracker

2. Backend Setup

cd backend
npm install
npm run dev
# or
node src/app.js

Create a .env file from .env.example:

cp .env.example .env

Configure MongoDB URI, Google OAuth, etc.

Backend runs on http://localhost:5001

3. Frontend Setup

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5173

4. Create a Feature Branch

git checkout -b feature/your-feature-name

---

📄 Environment Variables

Backend .env example:

MONGODB_URI=mongodb://localhost:27017/shuttle_tracker
GOOGLE_CLIENT_ID=your_google_client_id
JWT_SECRET=your_jwt_secret

Frontend .env (optional):

VITE_GOOGLE_CLIENT_ID=your_google_client_id

🔐 Important: .env.local is git-ignored — never push secrets.

---

✅ Development Checklist

Commit Message Format

type(scope): short description

Longer description (optional)

Closes #issue-number

Types: feat, fix, docs, style, refactor, test, chore

Push & PR

git add .
git commit -m "feat: add feature xyz"
git push -u origin feature/your-feature-name

• Open a Pull Request with a clear description.
• Reference issues like: Fixes #issue-no.

---

📱 Features

👩‍🎓 For Students

• 🗺️ Real-time Bus Tracking
• 📱 One-tap Pickup Request
• ⏰ ETA Predictions

🧑‍✈️ For Drivers

• 🗺️ Optimized Routes
• 📊 Trip Analytics

👨‍💼 For Administration

• 📈 Usage Analytics
• 🚌 Fleet Management
• 📊 Data Insights
• ⚙️ System Configuration

---

🛡️ Security Features

• Google OAuth Login (NST domain)
• JWT Token Authentication
• Rate Limiting & API Protection
• CORS Security
• Input Validation & Sanitization
• Environment Variables for Secrets

---

💬 Community Support

• Discussions: Open for Q&A
• Bug Reports: Use Issues with reproducible steps
• Feature Requests: Open an Issue with details
• Contact: Maintainers listed in repo

First-time contributors?

• Look for labels: good first issue, help wanted, documentation

---

📝 License

Released under MIT License.

---

Happy Contributing ❤️