How gdeep01/where-is-my-bus works
1. Overall shape
- This is a single-page React client with no custom backend.
- The runtime boundary is the browser: all UI, tracking logic, and map rendering happen client-side.
- External services are optional at runtime in demo mode, but in production the app depends on Firebase Realtime Database for live sync.
2. Primary user roles
- The app serves two roles from the same UI:
- Conductor mode: starts/stops a trip and publishes live GPS coordinates.
- Passenger mode: subscribes to active buses and watches a selected bus move on the map.
- There is no separate server-rendered admin surface or passenger app; both are views inside one React app.
3. UI composition
- src/App.jsx is the central orchestration point for the experience.
- The app is likely split into:
- a control/input area for bus number, route, and departure time,
- a sidebar/list of available buses,
- a Leaflet map view that shows the selected bus position.
- Styling is handled with src/App.css and src/index.css, so layout is mostly client-side presentation rather than framework-driven routing.
4. Live location acquisition
- The conductor browser uses the Geolocation API to poll GPS every few seconds.
- That location stream is the source of truth for an active trip.
- The app therefore depends on the conductor’s phone as both the sensor and the publisher; no dedicated GPS hardware is involved.
5. Realtime sync path
- The live data path is:
- browser geolocation
- Firebase Realtime Database write
- passenger-side Firebase onValue subscription
- React state update
- marker reposition on the map
- This is the core distributed-system boundary in the repo: the UI is local, but trip state is shared through Firebase.
6. Firebase integration boundary
- src/firebase.js is the runtime configuration layer for Firebase.
- src/firebase.example.js indicates the app can run with a placeholder/demo config or be wired to a real project by copying in credentials.
- The database appears to store active trips under a buses collection, and cleanup relies on Firebase’s onDisconnect behavior plus explicit delete on trip end.
7. Demo/offline-local boundary
- The README says the app runs in demo mode by default using localStorage.
- That makes the repo function in two modes:
- single-device local simulation without Firebase,
- cross-device live sync with Firebase enabled.
- This is important architecturally because production and demo share the same UI but differ in the persistence/sync layer.
8. Map and geospatial visualization
- The map layer is built with Leaflet + OpenStreetMap, which removes the need for a paid map API key.
- The map is a read-only visualization of trip state; it does not appear to own the tracking logic.
- The app also smooths movement and filters small GPS drift, so the map view is consuming processed positions rather than raw every-sample noise.
9. Static hosting and build pipeline
- The app is built with Vite and deployed as static assets, with Vercel as the hosting target.
- index.html and the public/ directory indicate a standard Vite static site layout.
- There is no API server, job worker, or custom deployment runtime in the repository.
10. Asset and PWA-related surface
- public/bg.mp4 suggests a branded/background media asset used by the client UI.
- The README says the app behaves like a PWA when added to the home screen, so the browser install experience is part of the product boundary even if service-worker code is not visible in the file tree.
- The repo also includes verification assets like google284635a01eceaec0.html, implying ownership/verification for hosting or search console rather than app logic.
11. Data lifecycle and cleanup
- A trip record is created when the conductor starts tracking, updated repeatedly, and deleted when the trip ends.
- Cleanup happens in three ways:
- immediate manual delete on “End Trip”,
- server-side onDisconnect cleanup if the browser disappears,
- client-side filtering of stale trips older than 24 hours.
- This keeps the shared bus list limited to currently relevant vehicles.
12. Engineering/tooling boundary
- src/App.test.jsx indicates at least one component-level test exists.
- eslint.config.js shows linting is part of the repo hygiene.
- These are supporting quality tools; they do not change the runtime architecture but matter for how the client is maintained.
13. Diagram-friendly summary
- The main architectural diagram should show:
- Conductor phone browser producing geolocation,
- Firebase Realtime Database as the shared state bus,
- Passenger browser subscribing and rendering the map,
- Leaflet/OpenStreetMap as the visualization layer,
- Vite/Vercel as the static build-and-host path,
- and a localStorage demo mode branch for offline/single-device use.
Main entry points: App.jsx App · vite.config.js Vite Build · firebase.js Firebase · index.jsx Entry
Components 21
React Client
Single-page browser UI and client-side state flow.
- App · Central orchestration of conductor and passenger views.
src/App.jsx - Controls · Bus number, route, and departure-time entry for starting trips.
src/App.jsx - Bus List · Available buses and active trip selection.
src/App.jsx - Trip State · Shared UI state for active trips, selection, and position updates.
src/App.jsx - GPS Poller · Browser location polling used by conductor mode.
src/App.jsx - Styles · Client-side presentation and layout styling.
src/App.css - App Test · Component-level test coverage for the main app.
src/App.test.jsx
Sync Layer
Local demo storage and optional realtime database integration.
- Trip Cleanup · Ends trips, clears stale records, and handles disconnect cleanup.
src/App.jsx - Firebase · Runtime configuration and realtime synchronization boundary.
src/firebase.js - Demo Store · Offline/single-device mode using local persistent storage.
README.md - Live Subscribe · Passenger-side realtime subscription to active buses.
src/App.jsx - Live Publish · Writes conductor location updates into shared trip records.
src/App.jsx
Map Layer
Trip visualization and geospatial rendering.
- Map View · Read-only visualization of the selected bus position.
src/App.jsx - Leaflet · Client mapping library used for marker and viewport rendering.
src/App.jsx - OpenStreetMap · Basemap tiles consumed by the Leaflet map.
src/App.jsx
Build & Host
Static build pipeline and hosting surface.
- Entry · Browser bootstrapping into the React app.
src/index.jsx - Vite Build · Static build pipeline for the client application.
vite.config.js - Shell HTML · Vite HTML host page and app mount point.
index.html - Vercel · Deployment target for the built client assets.
README.md - Background Video · Branded media asset used by the client UI.
public/bg.mp4 - Verification · Search or hosting verification asset.
public/google284635a01eceaec0.html
Connections 24
- Entry → App: mounts · Bootstraps the React application.
- App → Controls: renders · Main trip control area is composed inside the shell.
- App → Bus List: renders · Passenger bus list is composed inside the shell.
- App → Map View: renders · Map visualization is part of the main experience.
- App → Trip State: manages · Central state coordination for selection and trip data.
- Controls → GPS Poller: starts polling · Conductor mode begins geolocation tracking.
- GPS Poller → Live Publish: feeds · Polled GPS positions are published to shared state.
- Live Publish → Firebase: writes to · Primary production sync path.
- Live Publish → Demo Store: stores in · Demo mode persists locally when Firebase is absent.
- Firebase → Live Subscribe: serves · Passenger clients subscribe to active trip updates.
- Live Subscribe → Trip State: updates · Realtime events update React state.
- Trip State → Map View: positions · Selected bus position drives map marker updates.
- Map View → Leaflet: uses · Map rendering is handled by Leaflet.
- Leaflet → OpenStreetMap: tiles · Basemap imagery comes from OpenStreetMap.
- App → Trip Cleanup: ends trips · Manual end-trip and stale cleanup flow through the shell.
- Trip Cleanup → Firebase: deletes · Trip records are removed from shared storage.
- Trip Cleanup → Demo Store: clears · Local demo records are pruned as well.
- App → Styles: styled by · Client layout and presentation are CSS-driven.
- Vite Build → Shell HTML: serves · Build process starts from the HTML shell.
- Vite Build → Entry: bundles · Vite compiles the React entrypoint and app code.
- Vite Build → Vercel: deploys to · Built assets are hosted statically.
- App → Background Video: uses asset · UI includes branded background media.
- App → Verification: hosts asset · Verification file sits on the static host surface.
- App → App Test: covered by · Main app has component-level test coverage.