# imamhossain94/dhaka-metro-live-map architecture

> Architecture diagram of the GitHub repository imamhossain94/dhaka-metro-live-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imamhossain94/dhaka-metro-live-map
- Repository: https://github.com/imamhossain94/dhaka-metro-live-map

## Overview

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: [`src/App.jsx`](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/App.jsx) (App), [`src/simulation.js`](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/simulation.js) (Simulation), [`src/components/RealMap.jsx`](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/RealMap.jsx) (Real Map), [`src/components/Controls.jsx`](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/Controls.jsx) (Controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_node_main["Entry<br/>react bootstrap<br/>[main.jsx]"]
  node_node_app["App<br/>state orchestrator<br/>[App.jsx]"]
end

subgraph group_group_domain["Domain & Simulation"]
  node_node_sim["Simulation<br/>train engine<br/>[simulation.js]"]
  node_node_data[("MRT-6 Data<br/>domain dataset<br/>[data.js]")]
  node_node_geo["Schematic Geo<br/>route projection<br/>[geo.js]"]
  node_node_realroute["Real Route<br/>track geometry<br/>[realRoute.js]"]
  node_node_realgeo["Real Geo<br/>map adapter<br/>[realGeo.js]"]
end

subgraph group_group_views["Views"]
  node_node_metro["Metro Map<br/>schematic view<br/>[MetroMap.jsx]"]
  node_node_realmap["Real Map<br/>geospatial view<br/>[RealMap.jsx]"]
end

subgraph group_group_ui["Panels & Controls"]
  node_node_controls["Controls<br/>[Controls.jsx]"]
  node_node_trainlist["Train List<br/>status panel<br/>[TrainList.jsx]"]
  node_node_nextdepartures["Departures<br/>schedule panel<br/>[NextDepartures.jsx]"]
  node_node_fleetinfo["Fleet Info<br/>summary panel<br/>[FleetInfo.jsx]"]
  node_node_statusbar["Status Bar<br/>status panel<br/>[StatusBar.jsx]"]
  node_node_legend["Legend<br/>[Legend.jsx]"]
end

subgraph group_group_hooks["Browser Hooks"]
  node_node_geoloc["Geolocation<br/>browser hook<br/>[useGeolocation.js]"]
  node_node_media["Media Query<br/>responsive hook<br/>[useMediaQuery.js]"]
end

subgraph group_group_public["Static Assets"]
  node_node_farechart["Fare Chart<br/>static page"]
  node_node_pubdata["Public Data<br/>static json<br/>[mrt6_data.json]"]
end

subgraph group_group_external["External Inputs"]
  node_node_gps(("Geolocation API<br/>browser api"))
  node_node_tiles(("Map Tiles<br/>external map service"))
end

node_node_main -->|"mounts"| node_node_app
node_node_app -->|"computes"| node_node_sim
node_node_app -->|"passes state"| node_node_controls
node_node_app -->|"renders"| node_node_metro
node_node_app -->|"renders"| node_node_realmap
node_node_app -->|"feeds"| node_node_trainlist
node_node_app -->|"feeds"| node_node_nextdepartures
node_node_app -->|"feeds"| node_node_fleetinfo
node_node_app -->|"feeds"| node_node_statusbar
node_node_app -->|"shows"| node_node_legend
node_node_sim -->|"uses"| node_node_data
node_node_sim -->|"projects"| node_node_geo
node_node_sim -->|"projects"| node_node_realgeo
node_node_geo -->|"uses"| node_node_data
node_node_realgeo -->|"uses"| node_node_realroute
node_node_realmap -->|"maps trains"| node_node_realgeo
node_node_realmap -->|"tiles"| node_node_tiles
node_node_geoloc -->|"requests"| node_node_gps
node_node_controls -->|"adapts"| node_node_media
node_node_controls -->|"toggles"| node_node_geoloc
node_node_farechart -->|"loads"| node_node_pubdata

click node_node_main "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/main.jsx"
click node_node_app "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/App.jsx"
click node_node_sim "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/simulation.js"
click node_node_data "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/data.js"
click node_node_geo "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/geo.js"
click node_node_realroute "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/realRoute.js"
click node_node_realgeo "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/realGeo.js"
click node_node_controls "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/Controls.jsx"
click node_node_trainlist "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/TrainList.jsx"
click node_node_nextdepartures "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/NextDepartures.jsx"
click node_node_fleetinfo "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/FleetInfo.jsx"
click node_node_statusbar "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/StatusBar.jsx"
click node_node_legend "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/Legend.jsx"
click node_node_metro "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/MetroMap.jsx"
click node_node_realmap "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/RealMap.jsx"
click node_node_geoloc "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/hooks/useGeolocation.js"
click node_node_media "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/hooks/useMediaQuery.js"
click node_node_farechart "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/public/mrt6_fare_chart.html"
click node_node_pubdata "https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/public/mrt6_data.json"

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_node_main,node_node_app,node_node_gps,node_node_tiles toneBlue
class node_node_sim,node_node_data,node_node_geo,node_node_realroute,node_node_realgeo toneAmber
class node_node_metro,node_node_realmap toneMint
class node_node_controls,node_node_trainlist,node_node_nextdepartures,node_node_fleetinfo,node_node_statusbar,node_node_legend toneRose
class node_node_geoloc,node_node_media toneIndigo
class node_node_farechart,node_node_pubdata toneTeal
```

## Components

### App Shell

Client-side React app orchestration and bootstrapping.

- [Entry](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/main.jsx): react bootstrap · Vite entry point that mounts the app. · `src/main.jsx`
- [App](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/App.jsx): state orchestrator · Owns live time, mode, filters, and periodic refresh state. · `src/App.jsx`

### Domain & Simulation

Static MRT-6 data, schedule logic, and coordinate adapters.

- [Simulation](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/simulation.js): train engine · Computes active trains, dwell, headways, and schedule behavior from current time. · `src/simulation.js`
- [MRT-6 Data](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/data.js): domain dataset · Stations, route geometry, timetable rules, holidays, and constants. · `src/data.js`
- [Schematic Geo](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/geo.js): route projection · Projects simulated positions onto the schematic route polyline. · `src/geo.js`
- [Real Route](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/realRoute.js): track geometry · Real-world MRT-6 alignment and station coordinates. · `src/realRoute.js`
- [Real Geo](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/realGeo.js): map adapter · Maps simulated trains to latitude, longitude, and heading. · `src/realGeo.js`

### Views

Schematic and real-world map renderers.

- [Metro Map](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/MetroMap.jsx): schematic view · Renders the SVG-style schematic metro map. · `src/components/MetroMap.jsx`
- [Real Map](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/RealMap.jsx): geospatial view · Renders the real-world map view with train movement. · `src/components/RealMap.jsx`

### Panels & Controls

Interactive controls and informational side panels.

- [Controls](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/Controls.jsx): user controls · Time scrubbing, presets, live mode, and map toggles. · `src/components/Controls.jsx`
- [Train List](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/TrainList.jsx): status panel · Shows active trains and their current state. · `src/components/TrainList.jsx`
- [Departures](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/NextDepartures.jsx): schedule panel · Displays upcoming departures and countdowns. · `src/components/NextDepartures.jsx`
- [Fleet Info](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/FleetInfo.jsx): summary panel · Summarizes fleet usage and active service limits. · `src/components/FleetInfo.jsx`
- [Status Bar](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/StatusBar.jsx): status panel · Shows current app and simulation status. · `src/components/StatusBar.jsx`
- [Legend](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/components/Legend.jsx): map legend · Explains map symbols and route markers. · `src/components/Legend.jsx`

### Browser Hooks

Optional browser capabilities and responsive behavior.

- [Geolocation](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/hooks/useGeolocation.js): browser hook · Optional user location access for local positioning. · `src/hooks/useGeolocation.js`
- [Media Query](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/src/hooks/useMediaQuery.js): responsive hook · Drives mobile and desktop layout changes. · `src/hooks/useMediaQuery.js`

### Static Assets

Files served directly from the public root.

- [Fare Chart](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/public/mrt6_fare_chart.html): static page · Standalone fare and route lookup page served from public root. · `public/mrt6_fare_chart.html`
- [Public Data](https://github.com/imamhossain94/dhaka-metro-live-map/blob/main/public/mrt6_data.json): static json · 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**: browser api · Provides optional client GPS coordinates.
- **Map Tiles**: external map service · OpenStreetMap tiles and derived map geometry consumed by the real map.

## Connections

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