# kyle20192005/hk-next-transit architecture

> Architecture diagram of the GitHub repository kyle20192005/hk-next-transit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kyle20192005/hk-next-transit
- Repository: https://github.com/kyle20192005/hk-next-transit

## Overview

NextLeg is a Hong Kong transit arrivals and route-planning product, delivered as a web app and Expo app. The main journey is: a rider chooses a route or nearby stop, the backend loads transit data and obtains live arrivals, and the client presents ETAs, route details and maps. Separate branches cover rail and tram arrivals, nearby discovery, service news, and favorites. A data pipeline builds route, timetable and map datasets; a tracker service can serve shared live bus data. Some connections are documented rather than visible in sampled runtime code, so those links are cited to the README.

Main entry points: [`pipeline/build.py`](https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/build.py) (Transit data builder), [`apps/web/lib/data.ts`](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/lib/data.ts) (Route data access), [`apps/tracker/src/index.ts`](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/tracker/src/index.ts) (Tracker HTTP service), [`apps/web/app/api`](https://github.com/kyle20192005/hk-next-transit/tree/main/apps/web/app/api) (Transit API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Rider apps"]
  node_web["Web experience"]
  node_mobile["Mobile experience"]
end

subgraph group_api["Web API"]
  node_web_api["Transit API"]
  node_eta_endpoint["Route ETA endpoint<br/>[route.ts]"]
  node_nearby_endpoint["Nearby endpoint<br/>[route.ts]"]
  node_news_endpoint["Service news<br/>[route.ts]"]
  node_tram_endpoint["Tram endpoint<br/>[route.ts]"]
end

subgraph group_core["Transit logic"]
  node_live_client["Live client<br/>[tracker-client.ts]"]
  node_route_logic["Route and ETA logic<br/>[eta.ts]"]
  node_stop_live["Stop arrivals<br/>[stop-live.ts]"]
  node_minibus["Minibus support<br/>[gmb.ts]"]
  node_discovery["Nearby and search<br/>[stop-search.ts]"]
  node_rail_tram["Rail and tram"]
end

subgraph group_data["Transit data"]
  node_route_data["Route data access<br/>[data.ts]"]
  node_build_data["Transit data builder<br/>[build.py]"]
  node_gmb_data["Minibus data<br/>[gmb.py]"]
  node_other_data["Other route data<br/>[others.py]"]
  node_tram_data["Tram data<br/>[tram.py]"]
end

subgraph group_tracker["Live tracker"]
  node_tracker_service["Tracker HTTP service<br/>[index.ts]"]
  node_tracker_storage["Tracker data access<br/>[data.ts]"]
  node_upstream["Operator upstream<br/>[upstream.ts]"]
end

node_rider(("Rider"))
node_transit_sources(("Transit data sources"))

node_rider -->|"uses"| node_web
node_rider -->|"uses"| node_mobile
node_web -.->|"requests"| node_web_api
node_mobile -.->|"requests live data"| node_live_client
node_web_api -.->|"routes requests"| node_eta_endpoint
node_eta_endpoint -->|"uses"| node_route_logic
node_nearby_endpoint -->|"uses"| node_discovery
node_nearby_endpoint -->|"loads stops"| node_route_data
node_news_endpoint -->|"loads stops"| node_route_data
node_tram_endpoint -->|"uses"| node_rail_tram
node_tram_endpoint -->|"loads timetable"| node_route_data
node_stop_live -->|"uses"| node_minibus
node_live_client -->|"requests live feed"| node_tracker_service
node_live_client -->|"falls back to"| node_web_api
node_tracker_service -->|"loads transit data"| node_tracker_storage
node_tracker_service -->|"fetches arrivals"| node_upstream
node_tracker_service -->|"uses"| node_stop_live
node_transit_sources -.->|"provides source data"| node_build_data
node_build_data -->|"builds minibus data"| node_gmb_data
node_build_data -->|"uses route helpers"| node_other_data
node_build_data -->|"builds tram data"| node_tram_data
node_build_data -.->|"produces datasets"| node_route_data
node_route_data -.->|"serves API data"| node_web_api

click node_web "https://github.com/kyle20192005/hk-next-transit/tree/main/apps/web/app"
click node_mobile "https://github.com/kyle20192005/hk-next-transit/tree/main/apps/mobile/src/app"
click node_live_client "https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/tracker-client.ts"
click node_route_logic "https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/eta.ts"
click node_stop_live "https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/stop-live.ts"
click node_minibus "https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/gmb.ts"
click node_discovery "https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/stop-search.ts"
click node_rail_tram "https://github.com/kyle20192005/hk-next-transit/tree/main/packages/core/src"
click node_web_api "https://github.com/kyle20192005/hk-next-transit/tree/main/apps/web/app/api"
click node_eta_endpoint "https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/app/api/eta/route.ts"
click node_nearby_endpoint "https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/app/api/nearby/route.ts"
click node_news_endpoint "https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/app/api/news/route.ts"
click node_tram_endpoint "https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/app/api/tram/route.ts"
click node_route_data "https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/lib/data.ts"
click node_build_data "https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/build.py"
click node_gmb_data "https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/gmb.py"
click node_other_data "https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/others.py"
click node_tram_data "https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/tram.py"
click node_tracker_service "https://github.com/kyle20192005/hk-next-transit/blob/main/apps/tracker/src/index.ts"
click node_tracker_storage "https://github.com/kyle20192005/hk-next-transit/blob/main/apps/tracker/src/data.ts"
click node_upstream "https://github.com/kyle20192005/hk-next-transit/blob/main/apps/tracker/src/upstream.ts"

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_web,node_mobile toneBlue
class node_web_api,node_eta_endpoint,node_nearby_endpoint,node_news_endpoint,node_tram_endpoint toneAmber
class node_live_client,node_route_logic,node_stop_live,node_minibus,node_discovery,node_rail_tram toneMint
class node_route_data,node_build_data,node_gmb_data,node_other_data,node_tram_data toneRose
class node_tracker_service,node_tracker_storage,node_upstream,node_rider,node_transit_sources toneIndigo
```

## Components

### Rider apps

- [Web experience](https://github.com/kyle20192005/hk-next-transit/tree/main/apps/web/app): `apps/web/app`
- [Mobile experience](https://github.com/kyle20192005/hk-next-transit/tree/main/apps/mobile/src/app): `apps/mobile/src/app`

### Web API

- [Transit API](https://github.com/kyle20192005/hk-next-transit/tree/main/apps/web/app/api): `apps/web/app/api`
- [Route ETA endpoint](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/app/api/eta/route.ts): `apps/web/app/api/eta/route.ts`
- [Nearby endpoint](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/app/api/nearby/route.ts): `apps/web/app/api/nearby/route.ts`
- [Service news](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/app/api/news/route.ts): `apps/web/app/api/news/route.ts`
- [Tram endpoint](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/app/api/tram/route.ts): `apps/web/app/api/tram/route.ts`

### Transit logic

- [Live client](https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/tracker-client.ts): `packages/core/src/tracker-client.ts`
- [Route and ETA logic](https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/eta.ts): `packages/core/src/eta.ts`
- [Stop arrivals](https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/stop-live.ts): `packages/core/src/stop-live.ts`
- [Minibus support](https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/gmb.ts): `packages/core/src/gmb.ts`
- [Nearby and search](https://github.com/kyle20192005/hk-next-transit/blob/main/packages/core/src/stop-search.ts): `packages/core/src/stop-search.ts`
- [Rail and tram](https://github.com/kyle20192005/hk-next-transit/tree/main/packages/core/src): `packages/core/src`

### Transit data

- [Route data access](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/web/lib/data.ts): `apps/web/lib/data.ts`
- [Transit data builder](https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/build.py): `pipeline/build.py`
- [Minibus data](https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/gmb.py): `pipeline/gmb.py`
- [Other route data](https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/others.py): `pipeline/others.py`
- [Tram data](https://github.com/kyle20192005/hk-next-transit/blob/main/pipeline/tram.py): `pipeline/tram.py`

### Live tracker

- [Tracker HTTP service](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/tracker/src/index.ts): `apps/tracker/src/index.ts`
- [Tracker data access](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/tracker/src/data.ts): `apps/tracker/src/data.ts`
- [Operator upstream](https://github.com/kyle20192005/hk-next-transit/blob/main/apps/tracker/src/upstream.ts): `apps/tracker/src/upstream.ts`

### Other components

- **Rider**
- **Transit data sources**

## Connections

- Rider → Web experience: uses
- Rider → Mobile experience: uses
- Web experience → Transit API: requests
- Mobile experience → Live client: requests live data
- Transit API → Route ETA endpoint: routes requests
- Route ETA endpoint → Route and ETA logic: uses (evidence: `apps/web/app/api/eta/route.ts`)
- Nearby endpoint → Nearby and search: uses (evidence: `apps/web/app/api/nearby/route.ts`)
- Nearby endpoint → Route data access: loads stops (evidence: `apps/web/app/api/nearby/route.ts`)
- Service news → Route data access: loads stops (evidence: `apps/web/app/api/news/route.ts`)
- Tram endpoint → Rail and tram: uses (evidence: `apps/web/app/api/tram/route.ts`)
- Tram endpoint → Route data access: loads timetable (evidence: `apps/web/app/api/tram/route.ts`)
- Stop arrivals → Minibus support: uses (evidence: `packages/core/src/stop-live.ts`)
- Live client → Tracker HTTP service: requests live feed (evidence: `packages/core/src/tracker-client.ts`)
- Live client → Transit API: falls back to (evidence: `packages/core/src/tracker-client.ts`)
- Tracker HTTP service → Tracker data access: loads transit data (evidence: `apps/tracker/src/index.ts`)
- Tracker HTTP service → Operator upstream: fetches arrivals (evidence: `apps/tracker/src/index.ts`)
- Tracker HTTP service → Stop arrivals: uses (evidence: `apps/tracker/src/index.ts`)
- Transit data sources → Transit data builder: provides source data
- Transit data builder → Minibus data: builds minibus data (evidence: `pipeline/build.py`)
- Transit data builder → Other route data: uses route helpers (evidence: `pipeline/build.py`)
- Transit data builder → Tram data: builds tram data (evidence: `pipeline/build.py`)
- Transit data builder → Route data access: produces datasets
- Route data access → Transit API: serves API data
