How imamhossain94/dhaka-metro-live-map works
1. Overall shape
- This is a single-page, client-only React + Vite app. There is no backend API in the repo.
- All train movement, schedule logic, and UI state are computed in the browser from static data plus the user’s current time and optional GPS.
2. Primary application boundary
- src/App.jsx is the orchestrator.
- It owns the main UI state: live vs scrubbed time, schematic vs real-map mode, selected filters, and the periodic update loop (250ms per the README).
- It feeds computed simulation results into the map, sidebar, controls, and status components.
3. Domain data layer
- src/data.js is the core repository of MRT-6 domain data: stations, route geometry, timetable rules, and holiday definitions.
- It also appears to be the source for schedule-day classification and other constants used by the simulator.
- Static route/fare content is also published under public/ for direct browser access.
4. Simulation engine
- src/simulation.js is the heart of the “live” behavior.
- It converts the current Bangladesh Standard Time into active trains, departure countdowns, station dwell times, movement between stations, and fleet limits.
- The README indicates it models:
- official timetable / headway bands,
- ease-in/ease-out movement,
- platform dwell times,
- rush-hour adjustments,
- a maximum active fleet cap.
5. Schematic map geometry
- src/geo.js handles the schematic view’s spatial logic.
- Its main job is to project positions onto the route polyline, which is also used for snapping the user’s GPS position to the line in the schematic view.
- This is separate from real geographic coordinates; it is the abstraction used by the SVG-style map.
6. Real-world map geometry
- src/realRoute.js contains the real MRT-6 alignment and station coordinates.
- src/realGeo.js maps simulated train positions onto real latitude/longitude and heading, so the train glyphs can move along the OpenStreetMap/Leaflet map with correct orientation.
- This is the bridge between the simulation model and the real map rendering.
7. Map rendering split
- src/components/MetroMap.jsx renders the schematic map.
- src/components/RealMap.jsx renders the real-world map, likely using Leaflet and OpenStreetMap tiles.
- The README makes clear these are two separate views of the same simulation: one abstracted diagram, one geospatial track alignment.
8. Sidebar and control surface
- src/components/Controls.jsx manages user interaction such as time scrubbing, presets, and “Go Live”.
- TrainList.jsx, NextDepartures.jsx, FleetInfo.jsx, StatusBar.jsx, and Legend.jsx form the information panel around the map.
- These components consume simulation output rather than owning business logic, which keeps presentation separate from schedule math.
9. User location and responsive behavior
- src/hooks/useGeolocation.js enables the optional “show my location” feature.
- src/hooks/useMediaQuery.js drives responsive layout changes, especially the mobile behavior described in the README: a zoomed schematic viewport that can be panned vertically.
- The location feature is a browser capability boundary: GPS is opt-in and only affects the local client view.
10. Static assets and linked fare chart
- public/mrt6_fare_chart.html is a separate static page linked from the app for fare and route lookup.
- public/mrt6_data.json appears to support that chart or related offline data access.
- Because these files are in public/, they are served directly at the site root and are not bundled into the React component tree.
11. External services / data sources
- The real-map experience depends on OpenStreetMap tiles and Overpass API-derived geometry for the actual line alignment.
- The app also uses the browser’s Geolocation API for the user marker.
- All other train behavior is simulated, not live telemetry.
12. Important architectural boundary
- There are really two coordinate systems in play:
- simulation/schematic space for timetable-driven train logic and the diagram view,
- real geographic space for the OpenStreetMap view and route coordinates.
- The geo.js, realRoute.js, and realGeo.js modules are the adapters between those spaces.
- That separation is the key to diagramming the repo accurately.
13. Build and deployment
- This is a standard Vite app (vite.config.js, src/main.jsx).
- Production build outputs to dist/, and the README targets static deployment on Vercel.
- No server-side rendering, database, or queued background service is present in this repository.
Main entry points: App.jsx App · simulation.js Simulation · RealMap.jsx Real Map · Controls.jsx Controls
Components 21
App Shell
Client-side React app orchestration and bootstrapping.
Domain & Simulation
Static MRT-6 data, schedule logic, and coordinate adapters.
- Simulation · Computes active trains, dwell, headways, and schedule behavior from current time.
src/simulation.js - MRT-6 Data · Stations, route geometry, timetable rules, holidays, and constants.
src/data.js - Schematic Geo · Projects simulated positions onto the schematic route polyline.
src/geo.js - Real Route · Real-world MRT-6 alignment and station coordinates.
src/realRoute.js - Real Geo · Maps simulated trains to latitude, longitude, and heading.
src/realGeo.js
Views
Schematic and real-world map renderers.
Panels & Controls
Interactive controls and informational side panels.
- Controls · Time scrubbing, presets, live mode, and map toggles.
src/components/Controls.jsx - Train List · Shows active trains and their current state.
src/components/TrainList.jsx - Departures · Displays upcoming departures and countdowns.
src/components/NextDepartures.jsx - Fleet Info · Summarizes fleet usage and active service limits.
src/components/FleetInfo.jsx - Status Bar · Shows current app and simulation status.
src/components/StatusBar.jsx - Legend · Explains map symbols and route markers.
src/components/Legend.jsx
Browser Hooks
Optional browser capabilities and responsive behavior.
- Geolocation · Optional user location access for local positioning.
src/hooks/useGeolocation.js - Media Query · Drives mobile and desktop layout changes.
src/hooks/useMediaQuery.js
Static Assets
Files served directly from the public root.
- Fare Chart · Standalone fare and route lookup page served from public root.
public/mrt6_fare_chart.html - Public Data · Browser-served MRT-6 data for offline lookup or linked pages.
public/mrt6_data.json
External Inputs
Browser and map-provider dependencies outside the repo.
- Geolocation API · Provides optional client GPS coordinates.
- Map Tiles · OpenStreetMap tiles and derived map geometry consumed by the real map.
Connections 21
- Entry → App: mounts · Bootstraps the single-page app.
- App → Simulation: computes · Derives live train state from the current time.
- App → Controls: passes state · Feeds current mode and time into controls.
- App → Metro Map: renders · Supplies schematic view data and interactions.
- App → Real Map: renders · Supplies real-map view data and interactions.
- App → Train List: feeds · Provides train state for the sidebar.
- App → Departures: feeds · Provides upcoming departures and countdowns.
- App → Fleet Info: feeds · Provides fleet summary data.
- App → Status Bar: feeds · Provides app and simulation status.
- App → Legend: shows · Displays map legend alongside the view.
- Simulation → MRT-6 Data: uses · Reads stations, timetable rules, and constants.
- Simulation → Schematic Geo: projects · Converts simulated positions into schematic coordinates.
- Simulation → Real Geo: projects · Converts simulated positions into real-map coordinates.
- Schematic Geo → MRT-6 Data: uses · Consumes route geometry and station definitions.
- Real Geo → Real Route: uses · Consumes real alignment and station coordinates.
- Real Map → Real Geo: maps trains · Places train glyphs on the geographic view.
- Real Map → Map Tiles: tiles · Depends on external map tiles/service data.
- Geolocation → Geolocation API: requests · Uses the browser geolocation capability.
- Controls → Media Query: adapts · Adjusts behavior based on viewport size.
- Controls → Geolocation: toggles · Enables optional user-location display.
- Fare Chart → Public Data: loads · Uses public JSON data for lookup.