How mgks/githubtree works
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: index.js Tree core engine · script.js Browser explorer · shuffle-featured.cjs Featured rotation job · index-issue.cjs Issue indexer
Components 18
Interactive Web Exploration
- Web HTML shell
packages/web/index.html - Browser explorer
packages/web/src/script.js
CLI and Library
- Tree core engine
packages/core/index.js - CLI command and local state
packages/core/bin/cli.js
Catalog and Static Publishing
- Repository catalog
_data/repositories.csv - Featured homepage data
_data/featured-shuffled.json - SEO and static page generator
tools/generate-seo.js
Repository Curation Automation
- Issue indexer
tools/index-issue.cjs - Trending catalog updater
tools/update-repos.cjs - Featured rotation job
tools/shuffle-featured.cjs
Other components
- Repository explorer user
- GitHub REST API
- GitHub raw content CDN
- CLI operator
- Node package consumer
- Feature issue requester
- GitHub repository automation
- Scheduled maintenance event
Connections 29
- 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.