# gdeep01/where-is-my-bus architecture

> Architecture diagram of the GitHub repository gdeep01/where-is-my-bus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gdeep01/where-is-my-bus
- Repository: https://github.com/gdeep01/where-is-my-bus

## Overview

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: [`src/App.jsx`](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx) (App), [`vite.config.js`](https://github.com/gdeep01/where-is-my-bus/blob/main/vite.config.js) (Vite Build), [`src/firebase.js`](https://github.com/gdeep01/where-is-my-bus/blob/main/src/firebase.js) (Firebase), [`src/index.jsx`](https://github.com/gdeep01/where-is-my-bus/blob/main/src/index.jsx) (Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_app["App<br/>React shell<br/>[App.jsx]"]
  node_controls["Controls<br/>Trip input<br/>[App.jsx]"]
  node_buslist["Bus List<br/>Passenger view<br/>[App.jsx]"]
  node_tripstate(("Trip State<br/>Client state<br/>[App.jsx]"))
  node_location(("GPS Poller<br/>Geolocation<br/>[App.jsx]"))
  node_styles["Styles<br/>CSS layout<br/>[App.css]"]
  node_test["App Test<br/>Component test<br/>[App.test.jsx]"]
end

subgraph group_sync["Sync Layer"]
  node_cleanup(("Trip Cleanup<br/>Lifecycle<br/>[App.jsx]"))
  node_firebase[("Firebase<br/>Realtime DB<br/>[firebase.js]")]
  node_demo[("Demo Store<br/>localStorage<br/>[README.md]")]
  node_subscribe(("Live Subscribe<br/>onValue listener<br/>[App.jsx]"))
  node_publish(("Live Publish<br/>DB write<br/>[App.jsx]"))
end

subgraph group_viz["Map Layer"]
  node_mapview["Map View<br/>Leaflet view<br/>[App.jsx]"]
  node_leaflet(("Leaflet<br/>Mapping lib<br/>[App.jsx]"))
  node_osm(("OpenStreetMap<br/>Tile source<br/>[App.jsx]"))
end

subgraph group_delivery["Build & Host"]
  node_entry["Entry<br/>[index.jsx]"]
  node_vite["Vite Build<br/>Bundler<br/>[vite.config.js]"]
  node_html["Shell HTML<br/>Static entry<br/>[index.html]"]
  node_vercel["Vercel<br/>Static host<br/>[README.md]"]
  node_bg["Background Video<br/>Asset<br/>[bg.mp4]"]
  node_verify["Verification<br/>Ownership file"]
end

node_entry -->|"mounts"| node_app
node_app -->|"renders"| node_controls
node_app -->|"renders"| node_buslist
node_app -->|"renders"| node_mapview
node_app -->|"manages"| node_tripstate
node_controls -->|"starts polling"| node_location
node_location -->|"feeds"| node_publish
node_publish -->|"writes to"| node_firebase
node_publish -->|"stores in"| node_demo
node_firebase -->|"serves"| node_subscribe
node_subscribe -->|"updates"| node_tripstate
node_tripstate -->|"positions"| node_mapview
node_mapview -->|"uses"| node_leaflet
node_leaflet -->|"tiles"| node_osm
node_app -->|"ends trips"| node_cleanup
node_cleanup -->|"deletes"| node_firebase
node_cleanup -->|"clears"| node_demo
node_app -->|"styled by"| node_styles
node_vite -->|"serves"| node_html
node_vite -->|"bundles"| node_entry
node_vite -->|"deploys to"| node_vercel
node_app -->|"uses asset"| node_bg
node_app -->|"hosts asset"| node_verify
node_app -.->|"covered by"| node_test

click node_app "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_controls "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_buslist "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_tripstate "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_location "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_cleanup "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_firebase "https://github.com/gdeep01/where-is-my-bus/blob/main/src/firebase.js"
click node_demo "https://github.com/gdeep01/where-is-my-bus/blob/main/README.md"
click node_subscribe "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_publish "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_mapview "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_leaflet "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_osm "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx"
click node_styles "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.css"
click node_entry "https://github.com/gdeep01/where-is-my-bus/blob/main/src/index.jsx"
click node_vite "https://github.com/gdeep01/where-is-my-bus/blob/main/vite.config.js"
click node_html "https://github.com/gdeep01/where-is-my-bus/blob/main/index.html"
click node_vercel "https://github.com/gdeep01/where-is-my-bus/blob/main/README.md"
click node_bg "https://github.com/gdeep01/where-is-my-bus/blob/main/public/bg.mp4"
click node_verify "https://github.com/gdeep01/where-is-my-bus/blob/main/public/google284635a01eceaec0.html"
click node_test "https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.test.jsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_controls,node_buslist,node_tripstate,node_location,node_styles,node_test toneBlue
class node_cleanup,node_firebase,node_demo,node_subscribe,node_publish toneAmber
class node_mapview,node_leaflet,node_osm toneMint
class node_entry,node_vite,node_html,node_vercel,node_bg,node_verify toneRose
```

## Components

### React Client

Single-page browser UI and client-side state flow.

- [App](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): React shell · Central orchestration of conductor and passenger views. · `src/App.jsx`
- [Controls](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): Trip input · Bus number, route, and departure-time entry for starting trips. · `src/App.jsx`
- [Bus List](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): Passenger view · Available buses and active trip selection. · `src/App.jsx`
- [Trip State](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): Client state · Shared UI state for active trips, selection, and position updates. · `src/App.jsx`
- [GPS Poller](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): Geolocation · Browser location polling used by conductor mode. · `src/App.jsx`
- [Styles](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.css): CSS layout · Client-side presentation and layout styling. · `src/App.css`
- [App Test](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.test.jsx): Component 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](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): Lifecycle · Ends trips, clears stale records, and handles disconnect cleanup. · `src/App.jsx`
- [Firebase](https://github.com/gdeep01/where-is-my-bus/blob/main/src/firebase.js): Realtime DB · Runtime configuration and realtime synchronization boundary. · `src/firebase.js`
- [Demo Store](https://github.com/gdeep01/where-is-my-bus/blob/main/README.md): localStorage · Offline/single-device mode using local persistent storage. · `README.md`
- [Live Subscribe](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): onValue listener · Passenger-side realtime subscription to active buses. · `src/App.jsx`
- [Live Publish](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): DB write · Writes conductor location updates into shared trip records. · `src/App.jsx`

### Map Layer

Trip visualization and geospatial rendering.

- [Map View](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): Leaflet view · Read-only visualization of the selected bus position. · `src/App.jsx`
- [Leaflet](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): Mapping lib · Client mapping library used for marker and viewport rendering. · `src/App.jsx`
- [OpenStreetMap](https://github.com/gdeep01/where-is-my-bus/blob/main/src/App.jsx): Tile source · Basemap tiles consumed by the Leaflet map. · `src/App.jsx`

### Build & Host

Static build pipeline and hosting surface.

- [Entry](https://github.com/gdeep01/where-is-my-bus/blob/main/src/index.jsx): Vite entry · Browser bootstrapping into the React app. · `src/index.jsx`
- [Vite Build](https://github.com/gdeep01/where-is-my-bus/blob/main/vite.config.js): Bundler · Static build pipeline for the client application. · `vite.config.js`
- [Shell HTML](https://github.com/gdeep01/where-is-my-bus/blob/main/index.html): Static entry · Vite HTML host page and app mount point. · `index.html`
- [Vercel](https://github.com/gdeep01/where-is-my-bus/blob/main/README.md): Static host · Deployment target for the built client assets. · `README.md`
- [Background Video](https://github.com/gdeep01/where-is-my-bus/blob/main/public/bg.mp4): Asset · Branded media asset used by the client UI. · `public/bg.mp4`
- [Verification](https://github.com/gdeep01/where-is-my-bus/blob/main/public/google284635a01eceaec0.html): Ownership file · Search or hosting verification asset. · `public/google284635a01eceaec0.html`

## Connections

- 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.
