HubHop 🚆

Real-Time Sydney Transit Planner & Telemetry Dashboard 🌐 Live Demo: https://hubhop.vercel.app

HubHop is a high-performance, real-time transit routing application built for the Transport for NSW (TfNSW) network. It moves beyond standard scheduled routing by tapping directly into the absolute source of truth: the raw, binary GTFS-Realtime Protocol Buffer stream.

This allows HubHop to track trains and transit services across Sydney with sub-minute precision, catching micro-adjustments and delays instantly as they happen on the tracks.

---

📸 Live Demo Preview

---

⚡ Core Features

• True Real-Time Telemetry: Bypasses heavily cached JSON wrappers to decode the live TfNSW GTFS-Realtime binary stream directly on the edge.
• Adaptive String Calibration: Uses a custom prefix/suffix wildcard matching net to flawlessly link static Trip Planner API scheduled paths to their actively tracking sensor nodes, eliminating data drift.
• Resilient Fallback Architecture: Network timeouts from the TfNSW gateway are gracefully caught to prevent UI flashing. If the API key is missing or invalid, the app autonomously drops into a safe, localized Demo Mode.
• Modern UI/UX: Built with React & Tailwind CSS for a sleek, responsive, and dark-mode-first aesthetic.

---

🛠️ Technology Stack

• Framework: Next.js 15+ (App Router, React Server Components)
• Language: TypeScript
• Styling: Tailwind CSS (with Lucide React icons)
• Data Decoding: gtfs-realtime-bindings (for parsing binary Protocol Buffers)
• Data Source: TfNSW Open Data Hub
  • Trip Planner API (/v1/tp/trip)
  • GTFS-Realtime API (/v2/gtfs/realtime/sydneytrains)

---

🧠 Architecture Overview

HubHop operates on a Hybrid Orchestration Pipeline:

1. The Pathfinder: The frontend pings the backend with an origin and destination. The backend queries the TfNSW Trip Planner API to calculate the absolute optimal scheduled route.
2. The Telemetry Stream: Simultaneously, the backend downloads the live binary GTFS-Realtime array from the Sydney Trains network.
3. The Fusion: The app decodes the binary array and dynamically cross-references platform IDs and immutable tracking strings to fuse the real-time delay integers directly into the scheduled Pathfinder UI before sending it back to the client.

---

🚀 Getting Started

Follow these instructions to run HubHop on your local machine.

Prerequisites

• Node.js 18.x or later
• npm or yarn
• A free API key from the TfNSW Open Data Hub

1. Clone the Repository

git clone https://github.com/vishalvermauts/HubHop.git
cd HubHop

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env.local file in the root of the project and add your TfNSW API Key:

# .env.local
TFNSW_API_KEY=your_actual_tfnsw_open_data_token_here

(If you leave this out or use a placeholder, the app will automatically run in Demo Mode).

4. Run the Development Server

npm run dev

Open http://localhost:3000 with your browser to see the result. The page auto-updates as you edit the files.

---

🚢 Deployment

The easiest way to deploy HubHop is using the Vercel Platform.

1. Push your code to GitHub.
2. Import the project into Vercel.
3. Add your TFNSW_API_KEY to the Vercel Environment Variables.
4. Hit Deploy!

(Because HubHop uses Next.js force-dynamic API routes, your telemetry wrapper will run seamlessly on Vercel's Edge/Serverless functions).

---

Built with precision for the Sydney transit network.