Live bus tracking, ETAs, and routes — built with Next.js (App Router) and TailwindCSS, featuring Leaflet maps, Server-Sent Events for live updates, and a minimal driver simulator.

1. Overview
2. Features (MVP)
3. Tech Stack
4. Project Structure
5. Getting Started
6. Run Locally
7. Environment Variables
8. Available Scripts
9. Key Application Flows
10. Demo Guide
11. API Endpoints
12. API Reference
13. Frontend Routes
14. Data & Persistence
15. Real-Time Location Streaming
16. Testing & Quality
17. Deployment Checklist
18. Roadmap
19. Contributing
20. License
21. Notes

CityMover is a smart public transport OS designed for smaller cities, university towns, and government-run fleets that struggle with legacy systems. The platform closes the visibility gap between transport authorities, drivers, and commuters by combining live GPS tracking, digital ticketing, and proactive communications in a single product.

The project grew out of pilots with the Government of Punjab’s Higher Education Department, where bus fleets serving students and staff needed modern tooling without expensive proprietary hardware. CityMover therefore emphasizes low-bandwidth resilience, mobile-first UX, and integrations that work with existing infrastructure.

From the commuter perspective, the app surfaces real-time route information, predictive ETAs, and QR ticketing so that daily travel becomes predictable and cashless. Drivers get simple simulators or mobile dashboards to publish live updates. Transport officers view operational analytics, track fleet health, and reconcile digital payments.

A modular architecture lets CityMover extend to additional modes (e.g., trains) or integrate with municipal systems such as student ID portals, subsidy programs, and emergency alerts. The current codebase focuses on a fully functional bus operations MVP while laying the groundwork for multi-modal expansion.

• Live bus tracking on a map
• Search buses and view route info
• Select a stop to view ETAs (distance/speed based)
• Driver simulator to send mock GPS updates
• Authority dashboard with live locations and route stats
• PWA basics: manifest, theme-color, installable

• Next.js (App Router), React, TailwindCSS v4
• Leaflet + React-Leaflet for maps
• SSE for real-time location streaming
• In-memory mock data layer (buses, routes, stops, locations)
• MongoDB + Mongoose for persistent storage
• Razorpay for digital payments and settlement workflows
• Nodemailer for transactional email (OTP, password reset)
• Cloudinary for ticket and profile media storage

• src/lib/data.js — Mock data and in-memory location store
• src/lib/eta.js — ETA computation util
• src/lib/events.js — Simple pub/sub for streaming
• src/app/api/ — REST + SSE endpoints (legacy App Router prototype)
• src/pages/api/ — Primary Pages Router API endpoints for auth, payments, bookings, locations
• src/components/MapView.jsx — SSR-safe Leaflet map with SSE integration
• src/pages/index.js — Marketing landing page
• src/pages/BusTracker.js — Live tracking, trip planner, and booking entrypoint
• src/pages/BusBook.js — Ticket checkout view with Razorpay integration
• src/pages/api/auth/* — Authentication endpoints (signup, login, reset flows)
• src/pages/otp.js, src/pages/resetpassword.js — OTP verification and password reset UX
• src/models/ — Mongoose schemas for users, tickets, and supporting data
• src/lib/ — Shared utilities (dbConnect, nodemailer, imageUpload, validation schemas)
• middleware.ts — Session-aware middleware to guard protected routes
• public/manifest.json, public/icons/* — PWA assets

• Node.js ≥ 18.18 (Next.js 15 requirement)
• npm ≥ 9 (or compatible package manager)
• MongoDB instance (Atlas/local)
• Razorpay test keys for payment demos
• SMTP provider (e.g., Brevo, SES, Mailgun) for email flows
• Optional: Cloudinary account for media uploads

npm install

npm run dev
# open http://localhost:3000

npm run build
npm run start

1. Install deps (already done in scaffold):

   npm install

2. Start dev server:

   npm run dev

3. Open http://localhost:3000

If you recently edited the SSE stream (/api/stream/locations), fully restart the dev server to clear stale module state (Ctrl+C then npm run dev).

Create .env.local with:

Tip: Provide a .env.example to share expected keys with collaborators.

• npm run dev: Start the development server with hot reload.
• npm run build: Create an optimized production build.
• npm run start: Serve the production build.
• npm run lint: Run ESLint with the Next.js config.

• User signs up via src/pages/authpage.js.
• POST /api/auth/signup stores the user and dispatches OTP through sendOTPEmail() in src/lib/nodemailer.js.
• OTP verification occurs on src/pages/otp.js.
• Login (POST /api/auth/login) sets a secure, HTTP-only customUser cookie.
• Forgot password flow issues short-lived reset tokens via POST /api/auth/resetpasstoken.

• BusTracker directs the commuter to BusBook with pre-filled route, fare, and distance.
• Razorpay order is created using POST /api/payments/order with amount in paise.
• Signature verification occurs in POST /api/payments/verify, ensuring payment authenticity.
• POST /api/bookings/confirm persists ticket details and associates generated QR code with the user.
• Tickets render in src/pages/yourticket.js, enabling inspection and re-download.

• Drivers (or demo scripts) hit src/app/driver/page.js to emit location updates via POST /api/location/update.
• src/lib/events.js broadcasts through an in-memory pub/sub channel.
• /api/stream/locations exposes SSE for clients.
• src/components/MapView.jsx consumes the stream, throttles updates, and animates markers.

• /dashboard (App Router prototype) summarizes active buses, routes, and aggregated stats.
• Extend with role-based controls once JWT refresh tokens are introduced.

• Landing Page (/): explains product value and showcases features tailored to government stakeholders.
• Bus Tracker (/BusTracker): live map, trip planner, ETAs, and booking hand-off.
• Driver Simulator (/driver): choose a demo bus (e.g., b1, b3) and emit GPS updates every 3 seconds.
• Dashboard (/dashboard): observe total buses, active fleet counts, and live data table.
• Ticket Wallet (/yourticket): verify QR codes and ticket metadata after completing a payment flow.

• GET /api/buses → { buses, routes, stops }
• GET /api/location/:busId → Latest location for a specific bus
• POST /api/location/update → Push new location from driver app/simulator
• GET /api/eta/:stopId → ETAs for a stop
• GET /api/locations → Snapshot of all current locations
• GET /api/stream/locations → SSE stream (location + snapshot events)

Most endpoints return { success, message, data }. Always inspect the HTTP status code for errors.

• POST /api/auth/signup
  • Body: { fullName, email, password }
  • Result: Creates user, returns pending status, and emails OTP.
• POST /api/auth/login
  • Body: { email, password }
  • Result: Validates credentials and issues session cookie.
• POST /api/auth/logout
  • Result: Clears session cookie.
• POST /api/auth/resetpasstoken
  • Body: { email }
  • Result: Sends password reset email.
• POST /api/auth/resetpassword
  • Body: { token, password }
  • Result: Updates password after token validation.

• POST /api/payments/order
  • Body: { amountPaise, currency? }
  • Result: Returns Razorpay order payload + publishable key.
• POST /api/payments/verify
  • Body: { razorpay_payment_id, razorpay_order_id, razorpay_signature }
  • Result: Confirms payment authenticity.
• POST /api/bookings/confirm
  • Body: { ticketData }
  • Result: Persists ticket record.

• GET /api/buses
  • Returns master data for buses, routes, and stops.
• GET /api/location/:busId
  • Latest coordinates for a single bus.
• POST /api/location/update
  • Payload: { busId, lat, lng, speed, heading }.
  • Effect: Updates in-memory store and notifies subscribers.
• GET /api/eta/:stopId
  • Computes ETAs using heuristics in src/lib/eta.js.
• GET /api/locations
  • Snapshot of all active bus coordinates.
• GET /api/stream/locations
  • Server-Sent Events channel for real-time updates.

• / (src/pages/index.js): marketing and stakeholder narrative.
• /BusTracker (src/pages/BusTracker.js): commuter interface for tracking and booking.
• /BusBook (src/pages/BusBook.js): fare breakdown and payment flow.
• /yourticket (src/pages/yourticket.js): ticket wallet with QR retrieval.
• /trains (src/pages/trains.js): future module teaser for multimodal transport.
• /authpage, /otp, /resetpassword: authentication flows.
• /dashboard (src/app/dashboard/page.js): authority-facing dashboard (App Router).
• /driver (src/app/driver/page.js): driver simulator emitting location data.

• MongoDB models stored in src/models/ (users, tickets, routes, passes, etc.).
• src/lib/dbConnect.js maintains a singleton connection using mongoose.connect().
• Passwords hashed with bcryptjs; OTPs and reset tokens include expiry fields.
• Tickets store fare, distance, payment references, and QR image references.
• Consider offloading high-frequency location writes to Redis streams when scaling.

• Drivers (or IoT devices) post to /api/location/update with latest telemetry.
• src/lib/events.js publishes updates to subscribers.
• /api/stream/locations registers SSE connections and serves both initial snapshots and incremental updates.
• MapView.jsx buffers updates, uses requestAnimationFrame, and animates icons with heading-aware divIcon markers.
• Fallback polling via /api/locations ensures resilience if SSE disconnects.

• npm run lint keeps the codebase aligned with Next.js ESLint presets.
• Add component tests using React Testing Library for critical flows (auth, booking).
• Consider Cypress/Playwright end-to-end tests for multi-step journeys (sign-in → booking → ticket verification).
• Mock Razorpay, Nodemailer, and MongoDB in tests to avoid external dependencies.
• Continuous Integration suggestion: run lint + unit tests on every PR.

1. Provision MongoDB Atlas and whitelist hosting IPs.
2. Populate environment variables on hosting provider (Vercel, Netlify, Render, etc.).
3. Configure Razorpay webhooks for payment settlement confirmation.
4. Set SMTP credentials with a verified domain for higher deliverability.
5. Point NEXT_PUBLIC_BASE_URL to the production domain.
6. Monitor SSE connection counts; move to Redis pub/sub or Socket.io when scaling.
7. Enable HTTPS and HSTS for secure cookie transport.

• Migrate remaining Pages Router flows into App Router (or vice versa) for consistency.
• Switch from in-memory SSE store to Redis or Kafka for multi-instance deployments.
• Integrate Firebase Cloud Messaging for push notifications.
• Implement role-based access control with JWT refresh tokens and middleware guards.
• Expand /trains module via GTFS data ingestion.
• Add mobile apps (React Native/Expo) leveraging the same APIs.
• Introduce analytics for route performance and commuter retention.

1. Fork the repo and create a feature branch.
2. Install dependencies and set up .env.local.
3. Follow existing ESLint + Prettier rules; run npm run lint before committing.
4. Include screenshots for UI updates in PR descriptions.
5. Request reviews from maintainers; address feedback promptly.

Proprietary software for CityMover pilot programs. Reach out to maintainers for licensing discussions.

• This project uses an in-memory store for simplicity (ideal for hackathon/demo). Replace with a database (e.g., Postgres + Redis) for production.
• For push notifications, integrate Firebase Cloud Messaging.