# keithligh/hk-traffic-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/keithligh/hk-traffic-intelligence
- Repository: https://github.com/keithligh/hk-traffic-intelligence

## Overview

HK Traffic Intelligence is a public Hong Kong transport and weather dashboard, not a route planner. Visitors use a map and operations panel to compare road speeds, harbour crossings, boundary queues, weather warnings and public-transport arrivals; map stops can expose arrival details. API handlers obtain and shape published feeds, while shared upstream caching limits repeat requests. The README documents the major product areas; some route-to-UI wiring and unsampled subsystem internals are not visible in the excerpts, so those links are omitted rather than inferred.

Main entry points: [`src/lib`](https://github.com/keithligh/hk-traffic-intelligence/tree/main/src/lib) (Feed processors), [`src/lib/upstream.ts`](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/upstream.ts) (Upstream fetch and cache), [`src/components/dashboard.tsx`](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/dashboard.tsx) (Dashboard), [`src/components/city-map.tsx`](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/city-map.tsx) (Interactive map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Dashboard experience"]
  node_dashboard["Dashboard<br/>[dashboard.tsx]"]
  node_map["Interactive map<br/>[city-map.tsx]"]
  node_cards["Map detail cards<br/>[map-cards.ts]"]
  node_language["Language controls<br/>[locale.tsx]"]
  node_intel["Priority intel<br/>[intel.ts]"]
end

subgraph group_roads["Roads and conditions"]
  node_roadfeed["Road speeds<br/>[route.ts]"]
  node_approaches["Harbour approaches<br/>[route.ts]"]
  node_roadassets["Cameras and works<br/>[route.ts]"]
  node_incidents["Traffic incidents<br/>[route.ts]"]
  node_boundary["Boundary points<br/>[route.ts]"]
  node_weather["Warnings and weather<br/>[route.ts]"]
end

subgraph group_transit["Public transport"]
  node_rail["Rail arrivals<br/>[route.ts]"]
  node_light_rail["Light Rail arrivals<br/>[route.ts]"]
  node_bus["Bus arrivals<br/>[route.ts]"]
  node_citybus["Citybus arrivals<br/>[route.ts]"]
  node_minibus["Green minibus<br/>[route.ts]"]
  node_nlb["New Lantao Bus<br/>[route.ts]"]
  node_ferries["Ferry arrivals<br/>[route.ts]"]
  node_busboard["Stop boards<br/>[stop-board.ts]"]
end

subgraph group_feeds["Feed services"]
  node_feedlogic["Feed processors"]
  node_upstream["Upstream fetch and cache<br/>[upstream.ts]"]
  node_sharedcache[("Shared feed cache<br/>[feed-cache.ts]")]
end

node_visitor(("Visitor"))
node_publishers(("Public data publishers"))

node_visitor -->|"opens"| node_dashboard
node_dashboard -.->|"presents map"| node_map
node_dashboard -->|"surfaces priorities"| node_intel
node_map -->|"opens details"| node_cards
node_map -->|"uses locale"| node_language
node_cards -->|"formats text"| node_language
node_intel -->|"ranks warnings"| node_weather
node_roadfeed -->|"fetches feeds"| node_upstream
node_roadfeed -->|"builds corridors"| node_feedlogic
node_approaches -->|"fetches journey times"| node_upstream
node_approaches -->|"shapes points"| node_feedlogic
node_roadassets -->|"fetches layers"| node_upstream
node_roadassets -->|"enriches features"| node_feedlogic
node_incidents -->|"parses notices"| node_feedlogic
node_boundary -->|"shapes points"| node_feedlogic
node_weather -->|"fetches conditions"| node_upstream
node_weather -->|"parses weather"| node_feedlogic
node_rail -->|"loads arrivals"| node_feedlogic
node_light_rail -->|"loads arrivals"| node_feedlogic
node_bus -->|"loads arrivals"| node_feedlogic
node_citybus -->|"loads arrivals"| node_feedlogic
node_minibus -->|"loads arrivals"| node_feedlogic
node_nlb -->|"loads arrivals"| node_feedlogic
node_ferries -->|"loads sailings"| node_feedlogic
node_busboard -->|"assembles boards"| node_feedlogic
node_upstream -->|"reads and writes"| node_sharedcache
node_upstream -->|"requests feeds"| node_publishers

click node_dashboard "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/dashboard.tsx"
click node_map "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/city-map.tsx"
click node_cards "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/map-cards.ts"
click node_language "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/locale.tsx"
click node_intel "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/intel.ts"
click node_roadfeed "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/traffic/route.ts"
click node_approaches "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/approaches/route.ts"
click node_roadassets "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/picture/route.ts"
click node_incidents "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/incidents/route.ts"
click node_boundary "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/control-points/route.ts"
click node_weather "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/warnings/route.ts"
click node_rail "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/mtr/route.ts"
click node_light_rail "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/lrt/route.ts"
click node_bus "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/kmb/route.ts"
click node_citybus "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/citybus/route.ts"
click node_minibus "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/gmb/route.ts"
click node_nlb "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/nlb/route.ts"
click node_ferries "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/ferry/route.ts"
click node_busboard "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/stop-board.ts"
click node_feedlogic "https://github.com/keithligh/hk-traffic-intelligence/tree/main/src/lib"
click node_upstream "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/upstream.ts"
click node_sharedcache "https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/feed-cache.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_dashboard,node_map,node_cards,node_language,node_intel toneBlue
class node_roadfeed,node_approaches,node_roadassets,node_incidents,node_boundary,node_weather toneAmber
class node_rail,node_light_rail,node_bus,node_citybus,node_minibus,node_nlb,node_ferries,node_busboard toneMint
class node_feedlogic,node_upstream,node_sharedcache toneRose
class node_visitor,node_publishers toneIndigo
```

## Components

### Dashboard experience

- [Dashboard](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/dashboard.tsx): `src/components/dashboard.tsx`
- [Interactive map](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/city-map.tsx): `src/components/city-map.tsx`
- [Map detail cards](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/map-cards.ts): `src/components/map-cards.ts`
- [Language controls](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/components/locale.tsx): `src/components/locale.tsx`
- [Priority intel](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/intel.ts): `src/lib/intel.ts`

### Roads and conditions

- [Road speeds](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/traffic/route.ts): `src/app/api/traffic/route.ts`
- [Harbour approaches](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/approaches/route.ts): `src/app/api/approaches/route.ts`
- [Cameras and works](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/picture/route.ts): `src/app/api/picture/route.ts`
- [Traffic incidents](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/incidents/route.ts): `src/app/api/incidents/route.ts`
- [Boundary points](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/control-points/route.ts): `src/app/api/control-points/route.ts`
- [Warnings and weather](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/warnings/route.ts): `src/app/api/warnings/route.ts`

### Public transport

- [Rail arrivals](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/mtr/route.ts): `src/app/api/mtr/route.ts`
- [Light Rail arrivals](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/lrt/route.ts): `src/app/api/lrt/route.ts`
- [Bus arrivals](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/kmb/route.ts): `src/app/api/kmb/route.ts`
- [Citybus arrivals](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/citybus/route.ts): `src/app/api/citybus/route.ts`
- [Green minibus](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/gmb/route.ts): `src/app/api/gmb/route.ts`
- [New Lantao Bus](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/nlb/route.ts): `src/app/api/nlb/route.ts`
- [Ferry arrivals](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/app/api/ferry/route.ts): `src/app/api/ferry/route.ts`
- [Stop boards](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/stop-board.ts): `src/lib/stop-board.ts`

### Feed services

- [Feed processors](https://github.com/keithligh/hk-traffic-intelligence/tree/main/src/lib): `src/lib`
- [Upstream fetch and cache](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/upstream.ts): `src/lib/upstream.ts`
- [Shared feed cache](https://github.com/keithligh/hk-traffic-intelligence/blob/main/src/lib/feed-cache.ts): `src/lib/feed-cache.ts`

### Other components

- **Visitor**
- **Public data publishers**

## Connections

- Visitor → Dashboard: opens (evidence: `README.md`)
- Dashboard → Interactive map: presents map
- Dashboard → Priority intel: surfaces priorities
- Interactive map → Map detail cards: opens details (evidence: `src/components/city-map.tsx`)
- Interactive map → Language controls: uses locale (evidence: `src/components/city-map.tsx`)
- Map detail cards → Language controls: formats text (evidence: `src/components/map-cards.ts`)
- Priority intel → Warnings and weather: ranks warnings
- Road speeds → Upstream fetch and cache: fetches feeds (evidence: `src/app/api/traffic/route.ts`)
- Road speeds → Feed processors: builds corridors (evidence: `src/app/api/traffic/route.ts`)
- Harbour approaches → Upstream fetch and cache: fetches journey times (evidence: `src/app/api/approaches/route.ts`)
- Harbour approaches → Feed processors: shapes points (evidence: `src/app/api/approaches/route.ts`)
- Cameras and works → Upstream fetch and cache: fetches layers (evidence: `src/app/api/picture/route.ts`)
- Cameras and works → Feed processors: enriches features (evidence: `src/app/api/picture/route.ts`)
- Traffic incidents → Feed processors: parses notices (evidence: `src/app/api/incidents/route.ts`)
- Boundary points → Feed processors: shapes points (evidence: `src/app/api/control-points/route.ts`)
- Warnings and weather → Upstream fetch and cache: fetches conditions (evidence: `src/app/api/warnings/route.ts`)
- Warnings and weather → Feed processors: parses weather (evidence: `src/app/api/warnings/route.ts`)
- Rail arrivals → Feed processors: loads arrivals (evidence: `src/app/api/mtr/route.ts`)
- Light Rail arrivals → Feed processors: loads arrivals (evidence: `src/app/api/lrt/route.ts`)
- Bus arrivals → Feed processors: loads arrivals (evidence: `src/app/api/kmb/route.ts`)
- Citybus arrivals → Feed processors: loads arrivals (evidence: `src/app/api/citybus/route.ts`)
- Green minibus → Feed processors: loads arrivals (evidence: `src/app/api/gmb/route.ts`)
- New Lantao Bus → Feed processors: loads arrivals (evidence: `src/app/api/nlb/route.ts`)
- Ferry arrivals → Feed processors: loads sailings (evidence: `src/app/api/ferry/route.ts`)
- Stop boards → Feed processors: assembles boards (evidence: `src/app/api/board/route.ts`)
- Upstream fetch and cache → Shared feed cache: reads and writes (evidence: `src/lib/upstream.ts`)
- Upstream fetch and cache → Public data publishers: requests feeds (evidence: `src/lib/upstream.ts`)
