GitHub Project Galaxy

Turn a GitHub portfolio into a static profile graphic and an interactive project map.
One user-owned graph. Twelve visual views. No shared API call during normal viewing.

Open generator  ·  Live demo  ·  Quick start  ·  Presets  ·  Roadmap

---

🪐 One graph, 12 views Radial, three Galaxy variants, Obsidian-like, Tree, Treemap, Timeline, Cluster, Sunburst, Matrix and Sankey.

📦 User-owned artifacts Your profile repository stores project-map/galaxy.svg and project-map/graph.json.

⚡ Static-first README and viewer traffic read generated files instead of spending a shared GitHub REST quota.

🔎 Interactive exploration Search, focus, local graph depth, pan/zoom/pinch, activity overlay and repository-status filters.

What it does

Project Galaxy turns public GitHub repositories into a reusable portfolio graph. The same generated graph.json drives both a compact SVG for a profile README and twelve browser visualizations.

The generated data keeps repository status explicit: Original, Fork, Archived, and opt-in Contributed are never silently merged into one ownership meaning. Contributed is off by default and represents bounded public work in repositories owned by other people or organizations; it never means that you own those repositories. See docs/current-roadmap.md and docs/external-contributions-research.md.

Quick start

1. Open the public generator.
2. Enter your GitHub username and choose a theme, preset and repository filters. Enable Include Contributed only if you want bounded public work in repositories owned by others included; the default is off.
3. If you do not yet have the special USERNAME/USERNAME profile repository, use the guided Step 0 link to create it as a public repository.
4. Use Step 1 to copy the generated workflow and open GitHub's new-file editor at .github/workflows/project-map.yml.
5. Commit the workflow, then use Step 2 to run Update project map once.
6. Add the generated SVG to your profile README and link it to the interactive viewer.

The first run creates:

project-map/
├── galaxy.svg
└── graph.json

galaxy.svg remains the filename for backward compatibility regardless of the selected visual preset.

Embed it in a profile README

<p align="center">
  <a href="https://nekomario28.github.io/interactive-project-map/u/?username=USERNAME&style=galaxy-systems">
    <img width="740" src="https://raw.githubusercontent.com/USERNAME/USERNAME/HEAD/project-map/galaxy.svg" alt="USERNAME project map" />
  </a>
</p>

12 visual presets

radial remains the backward-compatible default. The legacy style=galaxy value aliases to galaxy-systems and is intentionally not a thirteenth preset.

Preset	Viewer route	Best for
radial	/radial/	compact profile README and general default
galaxy-classic	/u/	original one-galaxy atmosphere and global motion
galaxy-systems	/u/	clearest category → repository spatial membership
galaxy-hybrid	/u/	spiral atmosphere plus readable local systems
obsidian	/u/	organic force-directed exploration
tree	/tree/	explicit Owner → Category → Repository hierarchy
treemap	/treemap/	dense portfolio composition
timeline	/timeline/	repository creation history by category
cluster	/cluster/	category concentration in large portfolios
sunburst	/sunburst/	compact proportional hierarchy
matrix	/matrix/	Category × Language composition
sankey	/sankey/	Owner → Category → repository-status flow

All presets consume the same graph and preserve the same repository-status semantics. Archived repositories receive an additional dashed treatment where individual repository marks are drawn.

Galaxy Systems

Galaxy Systems is the default showcase because it makes hierarchy readable without leaving a permanent spoke network on screen. The owner is the center; categories form local systems; repositories orbit only their category. Hover/focus reveals the explanatory path when it is useful.

For static SVGs with at most 80 repositories, Galaxy Systems and Galaxy Hybrid can use script-free declarative SVG motion. Dense portfolios automatically fall back to bounded non-animated rendering.

Obsidian-like

The Obsidian-like view is an independently implemented deterministic force-directed graph. It is not affiliated with or endorsed by Obsidian or Dynalist Inc.; Obsidian is a trademark of Dynalist Inc.

Architecture

flowchart LR
  A[Public setup generator] --> B[USERNAME / USERNAME profile repository]
  B --> C[Scheduled GitHub Action]
  C --> D[project-map/galaxy.svg]
  C --> E[project-map/graph.json]
  D --> F[GitHub profile README]
  F -->|click| G[GitHub Pages viewer]
  G --> H[raw.githubusercontent.com]
  H --> E

Loading

The GitHub REST API is used when the user's Action refreshes repository metadata. Normal README views and interactive-map views consume the generated static files instead.

The generated caller workflow also isolates permissions:

generate
  contents: read
  reusable interactive-project-map workflow
       ↓ artifact
publish
  actions: read
  contents: write
  pinned GitHub-maintained Actions + fixed project-map paths

The reusable generator never receives the caller's write-capable publish token.

Interactive view controls

Shared Galaxy/Obsidian views support:

• Original / Fork / Archived visibility controls
• Activity freshness overlay using the already-generated updatedAt
• Focus / Local Graph with bounded depth
• search across repository metadata and taxonomy context
• shareable semantic URL state
• Motion ON / OFF

Dedicated views use the same repository-status projection rules, including removal of now-empty category nodes after filtering.

Static graph validation

Every viewer reads:

https://raw.githubusercontent.com/USERNAME/USERNAME/HEAD/project-map/graph.json

before rendering, and applies bounded validation. Among other checks:

• the requested username must be valid
• graph owner must match that username
• repository URLs must point to the expected public GitHub repository identity
• labels, topics, node counts and edge counts are bounded
• malformed nodes/URLs and unsupported edges are discarded

If the graph is missing or invalid, the viewer shows setup/recovery guidance instead of falling back to a shared API call.

Action inputs

Input	Default	Meaning
github_token	required	token used to read public GitHub metadata
username	caller owner	GitHub user to visualize
theme	dark	dark or light static SVG theme
style	radial	one of the 12 visible preset IDs; legacy galaxy aliases to galaxy-systems
max_repos	100	1–300 eligible repositories
forks	true	include forks
archived	false	include archived repositories
contributed	false	include bounded public contributions to repositories owned by others; never changes repository ownership
width	740	SVG width, 420–1600
height	420	SVG height, 260–1000
output_dir	project-map	relative output directory

Stable installs use the reusable generator channel @v1. Advanced users may pin a full reviewed 40-character generator commit SHA.

GitHub Pages and dormant one-click implementation

The production setup path is GitHub-owned:

GitHub repository + GitHub Actions + GitHub Pages

The Cloudflare Worker may still serve hosted previews/fallback, but GitHub App one-click onboarding is DORMANT / NOT_PRODUCTION_EXPOSED. Its small signed-state/callback implementation and security tests are retained in main for possible future reuse. Normal UI does not show the one-click control, and installer routes fail closed unless the separate explicit ENABLE_ONE_CLICK_INSTALLER=true gate and complete credentials are both present. The gate stays off unless concrete onboarding evidence or an explicit reviewed product decision justifies reactivation and the documented real-credential acceptance is then completed. Runtime secrets stay outside the public repository. See docs/current-roadmap.md, docs/github-only-architecture-decision.md and docs/github-app-one-click-installer.md.

Development

npm ci --ignore-scripts
npm run build:pages
npm run verify

Verification includes TypeScript checking, Wrangler dry-run, Node syntax checks, HTML validation, ESLint, Stylelint, actionlint, static graph validation, permission-isolation tests, dense 300-repository regressions, and renderer-specific gates across all twelve presets.

CI also renders all twelve presets from the same graph and uploads a visual comparison artifact on relevant changes.

Project status

The current roadmap, completed Contributed production proof, and remaining product/operations work are tracked in docs/current-roadmap.md.

Contributors & credits

Project contributors

Yuu / nekomario28 Maintainer · implementation

SYUN / syun88 Project contributor

GitHub's automatic Contributors view remains commit-authorship-driven. Research credits acknowledge public work that informed design decisions; they are not presented as Git co-authors or bundled dependencies.

Research & upstream credits

Graph Spawn spawn lifecycle · MIT	Persistent Graph simulation lifecycle · MIT	Node Factor connectivity sizing · MIT	d3-force force behavior reference · ISC
Sigma.js label density / LOD · MIT	MSAGLJS semantic zoom · MIT	Cytoscape.js label visibility threshold · MIT	MapLibre GL JS scale / collision policy · BSD-3-Clause
Stellarium FOV label disclosure · GPL-2.0 concept only	Atomic semantic-unit model · MIT	sift-kg schema discovery · MIT	GraphRAG hierarchical community reference · MIT

Detailed adoption and licensing boundaries are recorded in docs/licensing-audit-2026-08-21.md and the corresponding research notes.

License

MIT — copyright held collectively by the interactive-project-map contributors.