# warpshlczy/cityuhk-hub architecture

> Architecture diagram of the GitHub repository warpshlczy/cityuhk-hub, 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/warpshlczy/cityuhk-hub
- Repository: https://github.com/warpshlczy/cityuhk-hub

## Overview

CityUHK Hub is a multilingual directory for discovering and submitting CityUHK student projects. Contributors submit repository descriptions; the parser enriches and translates them into a static catalog, which the web app loads, filters, and presents as project cards and detail pages. The README documents category, tag, language, and author filters, shareable URL state, README rendering, and submission. Parser and UI links are based on excerpts or indexed references; links involving unsampled features are included only where documented.

Main entry points: [`repos-parser/src/build-index.mjs`](https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/build-index.mjs) (Index builder), [`web/src/App.tsx`](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/App.tsx) (Application routes), [`web/src/pages/HomePage.tsx`](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/pages/HomePage.tsx) (Browse projects), [`web/src/hooks/useProjects.ts`](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/hooks/useProjects.ts) (Project loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog generation"]
  node_parser["Index builder<br/>[build-index.mjs]"]
  node_frontmatter["Entry parsing<br/>[frontmatter.js]"]
  node_githubparse["GitHub metadata<br/>[github.js]"]
  node_markdown["README processing<br/>[markdown.js]"]
  node_translation["Translations<br/>[translate.js]"]
  node_aggregation["Catalog aggregates<br/>[aggregate.js]"]
  node_starhistory["Star history<br/>[starHistory.js]"]
end

subgraph group_discovery["Project discovery"]
  node_home["Browse projects<br/>[HomePage.tsx]"]
  node_projectstate["Project loading<br/>[useProjects.ts]"]
  node_searchbar["Search input<br/>[SearchBar.tsx]"]
  node_queryparser["Query syntax<br/>[searchParser.ts]"]
  node_search["Search and sorting<br/>[useSearch.ts]"]
  node_urlstate["Shareable URL state<br/>[useUrlState.ts]"]
end

subgraph group_details["Project details"]
  node_projectdetail["Project detail"]
  node_submit["Project submission<br/>[SubmitPage.tsx]"]
end

subgraph group_platform["Shared platform"]
  node_catalogapi["Catalog data access<br/>[projects.ts]"]
  node_githubapi["Runtime GitHub enrichment<br/>[github.ts]"]
  node_app["Application routes<br/>[App.tsx]"]
  node_i18n["Localization<br/>[index.tsx]"]
  node_statsapi["Visit statistics API<br/>[stats.js]"]
  node_redisclient["Redis REST client<br/>[upstash.js]"]
end

node_contributors(("Project contributors"))
node_redis[("Upstash Redis")]

node_contributors -.->|"submit entries"| node_parser
node_parser -->|"parses entries"| node_frontmatter
node_parser -->|"fetches metadata"| node_githubparse
node_parser -->|"analyzes README"| node_markdown
node_parser -->|"translates content"| node_translation
node_parser -->|"builds aggregates"| node_aggregation
node_parser -->|"reads snapshots"| node_starhistory
node_parser -.->|"writes catalog for"| node_catalogapi
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_projectdetail
node_app -->|"routes to"| node_submit
node_app -->|"tracks visit"| node_statsapi
node_statsapi -->|"uses client"| node_redisclient
node_redisclient -->|"sends pipeline"| node_redis
node_home -->|"loads projects"| node_projectstate
node_projectdetail -->|"loads project"| node_projectstate
node_projectstate -->|"fetches catalog"| node_catalogapi
node_projectstate -->|"enriches projects"| node_githubapi
node_home -->|"renders search"| node_searchbar
node_searchbar -->|"parses query"| node_queryparser
node_home -->|"filters projects"| node_search
node_search -->|"parses query"| node_queryparser
node_home -->|"syncs filters"| node_urlstate
node_i18n -->|"reads language"| node_urlstate
node_app -->|"provides localization"| node_i18n
node_submit -->|"uses GitHub API"| node_githubapi

click node_parser "https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/build-index.mjs"
click node_frontmatter "https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/frontmatter.js"
click node_githubparse "https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/github.js"
click node_markdown "https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/markdown.js"
click node_translation "https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/translate.js"
click node_aggregation "https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/aggregate.js"
click node_starhistory "https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/starHistory.js"
click node_catalogapi "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/api/projects.ts"
click node_githubapi "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/api/github.ts"
click node_home "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/pages/HomePage.tsx"
click node_projectstate "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/hooks/useProjects.ts"
click node_searchbar "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/components/SearchBar.tsx"
click node_queryparser "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/utils/searchParser.ts"
click node_search "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/hooks/useSearch.ts"
click node_urlstate "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/hooks/useUrlState.ts"
click node_projectdetail "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/pages/ProjectDetailPage.tsx"
click node_submit "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/pages/SubmitPage.tsx"
click node_app "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/App.tsx"
click node_i18n "https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/i18n/index.tsx"
click node_statsapi "https://github.com/warpshlczy/cityuhk-hub/blob/main/api/stats.js"
click node_redisclient "https://github.com/warpshlczy/cityuhk-hub/blob/main/lib/upstash.js"

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_parser,node_frontmatter,node_githubparse,node_markdown,node_translation,node_aggregation,node_starhistory toneBlue
class node_home,node_projectstate,node_searchbar,node_queryparser,node_search,node_urlstate,node_redis toneAmber
class node_projectdetail,node_submit toneMint
class node_catalogapi,node_githubapi,node_app,node_i18n,node_statsapi,node_redisclient toneRose
class node_contributors toneIndigo
```

## Components

### Catalog generation

- [Index builder](https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/build-index.mjs): `repos-parser/src/build-index.mjs`
- [Entry parsing](https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/frontmatter.js): `repos-parser/src/lib/frontmatter.js`
- [GitHub metadata](https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/github.js): `repos-parser/src/lib/github.js`
- [README processing](https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/markdown.js): `repos-parser/src/lib/markdown.js`
- [Translations](https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/translate.js): `repos-parser/src/lib/translate.js`
- [Catalog aggregates](https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/aggregate.js): `repos-parser/src/lib/aggregate.js`
- [Star history](https://github.com/warpshlczy/cityuhk-hub/blob/main/repos-parser/src/lib/starHistory.js): `repos-parser/src/lib/starHistory.js`

### Project discovery

- [Browse projects](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/pages/HomePage.tsx): `web/src/pages/HomePage.tsx`
- [Project loading](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/hooks/useProjects.ts): `web/src/hooks/useProjects.ts`
- [Search input](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/components/SearchBar.tsx): `web/src/components/SearchBar.tsx`
- [Query syntax](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/utils/searchParser.ts): `web/src/utils/searchParser.ts`
- [Search and sorting](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/hooks/useSearch.ts): `web/src/hooks/useSearch.ts`
- [Shareable URL state](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/hooks/useUrlState.ts): `web/src/hooks/useUrlState.ts`

### Project details

- [Project detail](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/pages/ProjectDetailPage.tsx): `web/src/pages/ProjectDetailPage.tsx`
- [Project submission](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/pages/SubmitPage.tsx): `web/src/pages/SubmitPage.tsx`

### Shared platform

- [Catalog data access](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/api/projects.ts): `web/src/api/projects.ts`
- [Runtime GitHub enrichment](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/api/github.ts): `web/src/api/github.ts`
- [Application routes](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Localization](https://github.com/warpshlczy/cityuhk-hub/blob/main/web/src/i18n/index.tsx): `web/src/i18n/index.tsx`
- [Visit statistics API](https://github.com/warpshlczy/cityuhk-hub/blob/main/api/stats.js): `api/stats.js`
- [Redis REST client](https://github.com/warpshlczy/cityuhk-hub/blob/main/lib/upstash.js): `lib/upstash.js`

### Other components

- **Project contributors**
- **Upstash Redis**

## Connections

- Project contributors → Index builder: submit entries
- Index builder → Entry parsing: parses entries (evidence: `repos-parser/src/build-index.mjs`)
- Index builder → GitHub metadata: fetches metadata (evidence: `repos-parser/src/build-index.mjs`)
- Index builder → README processing: analyzes README (evidence: `repos-parser/src/build-index.mjs`)
- Index builder → Translations: translates content (evidence: `repos-parser/src/build-index.mjs`)
- Index builder → Catalog aggregates: builds aggregates (evidence: `repos-parser/src/build-index.mjs`)
- Index builder → Star history: reads snapshots (evidence: `repos-parser/src/build-index.mjs`)
- Index builder → Catalog data access: writes catalog for
- Application routes → Browse projects: routes to (evidence: `web/src/App.tsx`)
- Application routes → Project detail: routes to (evidence: `web/src/App.tsx`)
- Application routes → Project submission: routes to (evidence: `web/src/App.tsx`)
- Application routes → Visit statistics API: tracks visit (evidence: `web/src/App.tsx`)
- Visit statistics API → Redis REST client: uses client (evidence: `api/stats.js`)
- Redis REST client → Upstash Redis: sends pipeline (evidence: `lib/upstash.js`)
- Browse projects → Project loading: loads projects (evidence: `web/src/pages/HomePage.tsx`)
- Project detail → Project loading: loads project (evidence: `web/src/pages/ProjectDetailPage.tsx`)
- Project loading → Catalog data access: fetches catalog (evidence: `web/src/hooks/useProjects.ts`)
- Project loading → Runtime GitHub enrichment: enriches projects (evidence: `web/src/hooks/useProjects.ts`)
- Browse projects → Search input: renders search (evidence: `web/src/pages/HomePage.tsx`)
- Search input → Query syntax: parses query (evidence: `web/src/components/SearchBar.tsx`)
- Browse projects → Search and sorting: filters projects (evidence: `web/src/pages/HomePage.tsx`)
- Search and sorting → Query syntax: parses query (evidence: `web/src/hooks/useSearch.ts`)
- Browse projects → Shareable URL state: syncs filters (evidence: `web/src/pages/HomePage.tsx`)
- Localization → Shareable URL state: reads language (evidence: `web/src/i18n/index.tsx`)
- Application routes → Localization: provides localization (evidence: `web/src/App.tsx`)
- Project submission → Runtime GitHub enrichment: uses GitHub API (evidence: `web/src/pages/SubmitPage.tsx`)
