# mgks/githubtree architecture

> Architecture diagram of the GitHub repository mgks/githubtree, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mgks/githubtree
- Repository: https://github.com/mgks/githubtree

## Overview

GitHubTree is a static web application, reusable Node.js library, and CLI for exploring GitHub repository trees without cloning. The main workflow is initiated by a repository explorer user entering a public repository and branch in the web dashboard; the browser retrieves the tree through GitHub’s API, processes it, and renders navigable, searchable output with optional file previews.

#### Components

##### Interactive web exploration
- **Repository explorer user** — **Path: null**. External actor who opens the site, supplies repository settings, searches the tree, and requests previews.
- **Web HTML shell** — **Path: `packages/web/index.html`**. Vite-served document containing the dashboard structure that bootstraps the browser application.
- **Browser explorer** — **Path: `packages/web/src/script.js`**. Maintains repository, sort/style, search, token, URL, selection, and preview state; wires UI events and uses the core engine to render trees.
- **Tree core engine** — **Path: `packages/core/index.js`**. Resolves branches, fetches recursive Git trees, filters by depth/ignore patterns, sorts hierarchical results, and generates ASCII or JSON output.
- **GitHub REST API** — **Path: null**. External source for repository metadata, commit SHAs, and recursive tree data.
- **GitHub raw content CDN** — **Path: null**. External source documented for direct, rate-limit-free code and media preview retrieval.

##### CLI and library entry points
- **CLI operator** — **Path: null**. External user or automation process invoking `gh-tree`.
- **CLI command and local state** — **Path: `packages/core/bin/cli.js`**. Parses flags, loads or saves the local PAT, maintains a 24-hour filesystem cache, invokes the engine, prints JSON/ASCII output, and attempts clipboard copying.
- **Node package consumer** — **Path: null**. External Node.js application embedding the documented `GitHubTree` library API.

##### Catalog and static publishing
- **Repository catalog** — **Path: `_data/repositories.csv`**. Curated repository directory containing repository, branch, language, and description metadata; it is distinct from live Git tree retrieval.
- **Featured homepage data** — **Path: `_data/featured-shuffled.json`**. Precomputed featured repository cards used by the homepage generator, alongside separate highlighted-repository state.
- **SEO and static page generator** — **Path: `tools/generate-seo.js`**. Parses catalog data, computes language statistics and featured content, injects it into the HTML template, and emits homepage and repository-specific static pages.

##### Repository curation automation
- **Feature issue requester** — **Path: null**. External GitHub user who submits a correctly prefixed feature or index request.
- **Issue indexer** — **Path: `tools/index-issue.cjs`**. Reads qualifying open issues, verifies requested repositories, appends valid metadata to the catalog, comments/closes issues, commits changes, and requests deployment.
- **Trending catalog updater** — **Path: `tools/update-repos.cjs`**. Queries GitHub repository search for recently created or active repositories and appends previously absent entries to the catalog.
- **Featured rotation job** — **Path: `tools/shuffle-featured.cjs`**. Selects a highlighted repository, optionally enriches it through GitHub, rewrites featured data, commits it, and requests deployment.
- **GitHub repository automation** — **Path: null**. External Git remote, Actions environment, and workflow-dispatch interface used by curation scripts for commits, pushes, and deployment triggers.
- **Scheduled maintenance event** — **Path: null**. External automation event that invokes repository-update or featured-rotation jobs; exact workflow wiring is not sampled.

#### Relationships

- **Repository explorer user -> Web HTML shell**: opens the deployed static dashboard; documented web-app entry point.
- **Web HTML shell -> Browser explorer**: bootstraps the Vite client application; supported by the web package structure and README’s Vite description.
- **Repository explorer user -> Browser explorer**: enters repository/branch values and activates fetch, search, sort, style, token, and preview controls; evidenced by DOM listeners and URL handling.
- **Browser explorer -> Tree core engine**: imports `GitHubTree` and uses its retrieval, sorting, and rendering capabilities.
- **Tree core engine -> GitHub REST API**: resolves a branch commit, falls back to repository default-branch metadata, and fetches the recursive tree.
- **GitHub REST API -> Tree core engine**: returns commit, repository, and tree payloads that become the engine’s `{ tree, truncated, branch }` result.
- **Tree core engine -> Browser explorer**: returns branch-aware tree data and processed output for display.
- **Browser explorer -> GitHub raw content CDN**: reads raw file or media content for detail previews; this behavior is documented, though the fetch implementation is outside the excerpt.
- **Browser explorer -> Repository explorer user**: renders the interactive tree, metadata, search results, controls, and preview dialogs.
- **CLI operator -> CLI command and local state**: supplies repository and command flags.
- **CLI command and local state -> Tree core engine**: calls tree retrieval on cache misses, then sorting and ASCII/JSON generation.
- **Tree core engine -> CLI command and local state**: returns fetched or generated tree data.
- **CLI command and local state -> CLI operator**: prints trees, errors, branch fallback notices, and clipboard status.
- **Node package consumer -> Tree core engine**: constructs the library class and calls its documented methods.
- **Repository catalog -> SEO and static page generator**: supplies repository listings and language metadata for homepage and repository-page generation.
- **Featured homepage data -> SEO and static page generator**: supplies shuffled featured cards and highlighted content.
- **SEO and static page generator -> Web HTML shell**: reads the template and emits populated homepage and repository route pages.
- **Feature issue requester -> Issue indexer**: creates qualifying GitHub issues containing repository requests.
- **Issue indexer -> GitHub REST API**: lists issues, verifies repository metadata, and posts comments.
- **Issue indexer -> Repository catalog**: appends validated repository metadata.
- **Issue indexer -> GitHub repository automation**: commits and pushes catalog changes and dispatches deployment.
- **Trending catalog updater -> GitHub REST API**: searches for candidate repositories.
- **Trending catalog updater -> Repository catalog**: appends new repository records.
- **Featured rotation job -> Repository catalog**: reads the current catalog and selects featured candidates.
- **Featured rotation job -> GitHub REST API**: optionally enriches the highlighted repository with stars, forks, language, and description.
- **Featured rotation job -> Featured homepage data**: writes refreshed featured and highlighted state.
- **Featured rotation job -> GitHub repository automation**: commits, pushes, and dispatches deployment.
- **Scheduled maintenance event -> Trending catalog updater**: invokes the repository refresh job; exact schedule is not sampled.
- **Scheduled maintenance event -> Featured rotation job**: invokes the featured refresh job; exact schedule is not sampled.

#### Coverage limits

The supplied web and generator files are partial. Exact preview-fetch code, HTML script tags, client rendering functions, generated output layout, and GitHub Actions workflow-to-tool mappings could not be established directly. No server-side application or database is evidenced; the documented architecture is primarily static hosting, browser execution, direct GitHub API access, and filesystem/git-backed catalog automation.

Main entry points: [`packages/core/index.js`](https://github.com/mgks/githubtree/blob/main/packages/core/index.js) (Tree core engine), [`packages/web/src/script.js`](https://github.com/mgks/githubtree/blob/main/packages/web/src/script.js) (Browser explorer), [`tools/shuffle-featured.cjs`](https://github.com/mgks/githubtree/blob/main/tools/shuffle-featured.cjs) (Featured rotation job), [`tools/index-issue.cjs`](https://github.com/mgks/githubtree/blob/main/tools/index-issue.cjs) (Issue indexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Interactive Web Exploration"]
  node_web_shell["Web HTML shell<br/>static document"]
  node_browser_explorer["Browser explorer<br/>browser application"]
end

subgraph group_cli["CLI and Library"]
  node_tree_engine["Tree core engine<br/>library engine"]
  node_cli_state["CLI command and local state<br/>CLI and cache"]
end

subgraph group_publishing["Catalog and Static Publishing"]
  node_repo_catalog["Repository catalog<br/>catalog data"]
  node_featured_data["Featured homepage data<br/>featured data"]
  node_seo_generator["SEO and static page generator<br/>static generator"]
end

subgraph group_curation["Repository Curation Automation"]
  node_issue_indexer["Issue indexer<br/>curation tool"]
  node_trending_updater["Trending catalog updater<br/>curation tool"]
  node_featured_rotation["Featured rotation job<br/>curation tool"]
end

node_repo_explorer(("Repository explorer user<br/>external actor"))
node_github_api{{"GitHub REST API<br/>external API"}}
node_raw_cdn{{"GitHub raw content CDN<br/>external CDN"}}
node_cli_operator(("CLI operator<br/>external actor"))
node_node_consumer(("Node package consumer<br/>external application"))
node_feature_requester(("Feature issue requester<br/>external actor"))
node_github_automation{{"GitHub repository automation<br/>external automation"}}
node_maintenance_event(("Scheduled maintenance event<br/>external event"))

node_repo_explorer -->|"opens dashboard"| node_web_shell
node_web_shell -->|"bootstraps app"| node_browser_explorer
node_repo_explorer -->|"controls exploration"| node_browser_explorer
node_browser_explorer -->|"uses engine"| node_tree_engine
node_tree_engine -->|"fetches trees"| node_github_api
node_github_api -->|"returns tree data"| node_tree_engine
node_tree_engine -->|"returns processed output"| node_browser_explorer
node_browser_explorer -->|"reads previews"| node_raw_cdn
node_browser_explorer -->|"renders exploration"| node_repo_explorer
node_cli_operator -->|"supplies flags"| node_cli_state
node_cli_state -->|"calls engine"| node_tree_engine
node_tree_engine -->|"returns tree data"| node_cli_state
node_cli_state -->|"prints results"| node_cli_operator
node_node_consumer -->|"uses library"| node_tree_engine
node_repo_catalog -->|"supplies listings"| node_seo_generator
node_featured_data -->|"supplies featured data"| node_seo_generator
node_seo_generator -->|"emits static pages"| node_web_shell
node_feature_requester -->|"creates feature issues"| node_issue_indexer
node_issue_indexer -->|"verifies requests"| node_github_api
node_issue_indexer -->|"appends metadata"| node_repo_catalog
node_issue_indexer -->|"commits and deploys"| node_github_automation
node_trending_updater -->|"searches repositories"| node_github_api
node_trending_updater -->|"appends records"| node_repo_catalog
node_featured_rotation -->|"selects candidates"| node_repo_catalog
node_featured_rotation -.->|"enriches repository"| node_github_api
node_featured_rotation -->|"writes featured state"| node_featured_data
node_featured_rotation -->|"commits and deploys"| node_github_automation
node_maintenance_event -.->|"invokes refresh"| node_trending_updater
node_maintenance_event -.->|"invokes rotation"| node_featured_rotation

click node_web_shell "https://github.com/mgks/githubtree/blob/main/packages/web/index.html"
click node_browser_explorer "https://github.com/mgks/githubtree/blob/main/packages/web/src/script.js"
click node_tree_engine "https://github.com/mgks/githubtree/blob/main/packages/core/index.js"
click node_cli_state "https://github.com/mgks/githubtree/blob/main/packages/core/bin/cli.js"
click node_repo_catalog "https://github.com/mgks/githubtree/blob/main/_data/repositories.csv"
click node_featured_data "https://github.com/mgks/githubtree/blob/main/_data/featured-shuffled.json"
click node_seo_generator "https://github.com/mgks/githubtree/blob/main/tools/generate-seo.js"
click node_issue_indexer "https://github.com/mgks/githubtree/blob/main/tools/index-issue.cjs"
click node_trending_updater "https://github.com/mgks/githubtree/blob/main/tools/update-repos.cjs"
click node_featured_rotation "https://github.com/mgks/githubtree/blob/main/tools/shuffle-featured.cjs"

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_shell,node_browser_explorer,node_repo_explorer toneBlue
class node_tree_engine,node_cli_state toneAmber
class node_repo_catalog,node_featured_data,node_seo_generator,node_github_api,node_feature_requester toneMint
class node_issue_indexer,node_trending_updater,node_featured_rotation toneRose
class node_raw_cdn,node_cli_operator,node_node_consumer,node_github_automation,node_maintenance_event toneIndigo
```

## Components

### Interactive Web Exploration

- [Web HTML shell](https://github.com/mgks/githubtree/blob/main/packages/web/index.html): static document · `packages/web/index.html`
- [Browser explorer](https://github.com/mgks/githubtree/blob/main/packages/web/src/script.js): browser application · `packages/web/src/script.js`

### CLI and Library

- [Tree core engine](https://github.com/mgks/githubtree/blob/main/packages/core/index.js): library engine · `packages/core/index.js`
- [CLI command and local state](https://github.com/mgks/githubtree/blob/main/packages/core/bin/cli.js): CLI and cache · `packages/core/bin/cli.js`

### Catalog and Static Publishing

- [Repository catalog](https://github.com/mgks/githubtree/blob/main/_data/repositories.csv): catalog data · `_data/repositories.csv`
- [Featured homepage data](https://github.com/mgks/githubtree/blob/main/_data/featured-shuffled.json): featured data · `_data/featured-shuffled.json`
- [SEO and static page generator](https://github.com/mgks/githubtree/blob/main/tools/generate-seo.js): static generator · `tools/generate-seo.js`

### Repository Curation Automation

- [Issue indexer](https://github.com/mgks/githubtree/blob/main/tools/index-issue.cjs): curation tool · `tools/index-issue.cjs`
- [Trending catalog updater](https://github.com/mgks/githubtree/blob/main/tools/update-repos.cjs): curation tool · `tools/update-repos.cjs`
- [Featured rotation job](https://github.com/mgks/githubtree/blob/main/tools/shuffle-featured.cjs): curation tool · `tools/shuffle-featured.cjs`

### Other components

- **Repository explorer user**: external actor
- **GitHub REST API**: external API
- **GitHub raw content CDN**: external CDN
- **CLI operator**: external actor
- **Node package consumer**: external application
- **Feature issue requester**: external actor
- **GitHub repository automation**: external automation
- **Scheduled maintenance event**: external event

## Connections

- Repository explorer user → Web HTML shell: opens dashboard
- Web HTML shell → Browser explorer: bootstraps app
- Repository explorer user → Browser explorer: controls exploration
- Browser explorer → Tree core engine: uses engine
- Tree core engine → GitHub REST API: fetches trees
- GitHub REST API → Tree core engine: returns tree data
- Tree core engine → Browser explorer: returns processed output
- Browser explorer → GitHub raw content CDN: reads previews
- Browser explorer → Repository explorer user: renders exploration
- CLI operator → CLI command and local state: supplies flags
- CLI command and local state → Tree core engine: calls engine
- Tree core engine → CLI command and local state: returns tree data
- CLI command and local state → CLI operator: prints results
- Node package consumer → Tree core engine: uses library
- Repository catalog → SEO and static page generator: supplies listings
- Featured homepage data → SEO and static page generator: supplies featured data
- SEO and static page generator → Web HTML shell: emits static pages
- Feature issue requester → Issue indexer: creates feature issues
- Issue indexer → GitHub REST API: verifies requests
- Issue indexer → Repository catalog: appends metadata
- Issue indexer → GitHub repository automation: commits and deploys
- Trending catalog updater → GitHub REST API: searches repositories
- Trending catalog updater → Repository catalog: appends records
- Featured rotation job → Repository catalog: selects candidates
- Featured rotation job → GitHub REST API: enriches repository
- Featured rotation job → Featured homepage data: writes featured state
- Featured rotation job → GitHub repository automation: commits and deploys
- Scheduled maintenance event → Trending catalog updater: invokes refresh · Exact workflow wiring is not sampled.
- Scheduled maintenance event → Featured rotation job: invokes rotation · Exact workflow wiring is not sampled.
