🚌 RouteSync

Enterprise-Grade Real-Time Transit Tracking Platform

Live Geospatial Mapping · Role-Based Access Control · Serverless Architecture

🌐 Live Demo · 🐛 Report Bug · 💡 Request Feature · 📖 Contributing

---

📋 Table of Contents

• Overview
• System Architecture
• Engineering Highlights
• Live Demo & Sandbox
• Role-Based Access Control (RBAC)
• Tech Stack
• Getting Started (Local Development)
• Deployment (Vercel)
• API Reference
• Author

---

🎯 Overview

RouteSync is a production-style, full-stack transit tracking platform engineered to solve the challenges of real-time geospatial data synchronization. Designed to support three distinct user personas (Passengers, Drivers, and System Administrators), the application delivers interactive maps, a securely authenticated RESTful API, and near real-time GPS telemetry broadcasting.

Built as a comprehensive portfolio piece, RouteSync demonstrates mastery of modern web architecture patterns, including modular frontend design, dual-mode data persistence, serverless deployment, and strict role-based access control.

---

📸 Application Showcase

Platform Landing Page

Modern, responsive entry point with role-based routing

Admin Route Digitization

Full CRUD operations and geospatial drawing using Leaflet.draw

Passenger Route Selection

Browse active routes and view live fleet statistics

Passenger Live Tracking

Real-time bus movement, intelligent ETAs, and occupancy monitoring

Live Driver Telemetry

Live telemetry broadcasting and route assignment

---

🏗️ System Architecture

RouteSync employs a robust, environment-aware architecture designed for both rapid local development and scalable edge deployment.

flowchart TB
  subgraph Client ["🌐 Client Layer (Browser)"]
    UI["Vanilla ES Modules<br/>State Management"]
    Maps["🗺️ Leaflet Geospatial UI"]
    UI --> Maps
  end

  subgraph Local ["💻 Local Development Environment"]
    UI -->|"REST + WebSockets (Socket.IO)"| Express["Node.js / Express<br/>API Gateway"]
    Express --> Files[("📁 Local JSON Persistence")]
  end

  subgraph Prod ["☁️ Production Environment (Vercel)"]
    UI -->|"REST + HTTP Polling"| API["Serverless Functions<br/>(Edge Optimized)"]
    API --> Redis[("💾 Upstash Redis Cluster")]
  end

Loading

Key Architectural Decisions

• Dual-Mode Persistence Layer: The application dynamically detects its execution environment. In local development, it utilizes file-system JSON storage for zero-configuration startup. When deployed to Vercel, it seamlessly transitions to a highly available Upstash Redis cluster to support the ephemeral, read-only nature of serverless functions.
• Protocol Fallbacks: Real-time data streams via Socket.IO during local execution, but gracefully degrades to intelligent HTTP polling in serverless environments where persistent socket connections are unsupported.
• Zero-Build Frontend: The frontend eschews complex build steps in favor of native ES Modules, drastically reducing deployment times while maintaining strict modularity and separation of concerns.

---

⭐ Engineering Highlights

• 🗺️ Geospatial Processing: Interactive Leaflet maps with dynamic route polylines, auto-calculating bounding boxes, and real-time coordinate validation.
• 🔐 Stateless Authentication: Secure JWT-based authentication flow with bcrypt password hashing, ensuring secure token issuance without session overhead.
• ⏱️ Algorithmic ETA Calculation: Real-time predictive ETAs computed on the backend using the Haversine formula to calculate the distance between active bus coordinates and the remaining route polyline.
• 🛡️ Defensive API Design: Comprehensive backend validation to prevent malformed coordinate injection, unauthorized route mutations, and abuse.

---

🌐 Live Demo & Sandbox

I have deployed a live "Sandbox" environment tailored for recruiters and technical reviewers.

👉 route-sync-five.vercel.app

🔑 Demo Credentials

Role	Email	Password
🚍 Driver	demo-driver@routesync.app	demo1234
🛡️ Admin	demo-admin@routesync.app	demo1234

🔒 Security Note: To preserve the integrity of the live demo for all reviewers, the demo-admin account is locked into a Read-Only Mode. You may access all dashboards, but write operations (POST, PUT, DELETE) to the routing tables will gracefully return a 403 Forbidden.

---

🛡️ Role-Based Access Control (RBAC)

The application strictly enforces permission boundaries across three distinct authorization tiers:

Persona	Authentication	Capabilities
🧑‍🤝‍🧑 Passenger	Unauthenticated	Browse network, view live telemetry, access ETAs, read/write public reviews.
🚍 Driver	JWT Required	Transmit GPS telemetry, manage trip lifecycle (Offline → Ready → Active → Completed).
🛡️ Admin	JWT Required	Full CRUD authority over the routing network. Utilize Leaflet.draw to digitize new routes directly onto the map interface.

---

🛠️ Tech Stack

Layer	Technologies
🎨 User Interface	HTML5, CSS3, Custom Design System, Font Awesome
🧩 Frontend Logic	JavaScript (ES6+), Vanilla ES Modules, Leaflet.js
⚙️ Backend API	Node.js (JavaScript), Express.js, JWT, bcryptjs
📡 Real-Time Data	Socket.IO (Local) / HTTP Polling (Serverless)
💾 Persistence	File System (JSON) / Upstash Redis
☁️ Infrastructure	Vercel CDN, Vercel Serverless Functions, Vercel Cron Jobs

---

🚀 Getting Started (Local Development)

Prerequisites

• Node.js (v18 or higher)
• npm

Installation

# 1. Clone the repository
git clone https://github.com/Omcodesk/RouteSync.git
cd RouteSync

# 2. Install dependencies
npm install

# 3. Configure Environment Variables
cp .env.example backend/.env
# (Optional) Update backend/.env with your local configurations

# 4. Spin up the local server
npm start

The application will be available at http://localhost:3000.

---

☁️ Deployment (Vercel)

Deploying RouteSync to a production environment requires setting up the Upstash Redis integration.

1. Push your repository to GitHub and import it into Vercel.
2. Navigate to your Vercel project's Storage tab.
3. Connect a new Upstash Redis database. Vercel will automatically inject the required KV_REST_API_URL and KV_REST_API_TOKEN environment variables.
4. Set the following environment variables in Vercel:
   • JWT_SECRET: A secure, randomized cryptographic string.
   • CRON_SECRET: Required to secure the /api/demo/tick endpoint.
5. Trigger a Redeploy.

---

📡 API Reference

A brief overview of the RESTful endpoints powering RouteSync:

Method	Endpoint	Auth Required	Purpose
GET	/api/health	-	Microservice health check & storage status
GET	/api/routes	-	Fetch active routing topologies
POST	/api/auth/login	-	Issue JWT for authenticated sessions
POST	/api/routes	Admin	Persist a newly digitized route
POST	/api/driver/update	Driver	Ingest live GPS telemetry payload
GET	/api/buses	-	Retrieve aggregated fleet coordinates

---

👨‍💻 Author

Om Chaddha · Software Engineer

---

📄 Licensing & Open Source

This project is open-source and available under the MIT License.

• Security: Review our Security Policy before reporting vulnerabilities.
• Contributing: See Contributing Guidelines for architectural constraints and PR workflows.

*Engineered by Omcodesk © 2026*