Redesign: On-demand architecture docs generation UX

[jonathanpopham]

Context

We previously attempted several approaches to let users generate architecture docs for any public GitHub repo (PRs #3, #5, #6 — all reverted/closed). Each had significant UX or security issues:

• PR Add 'Request a Repo' button and issue template #3: Redirect to GitHub Issue form → takes users off the page, terrible flow
• PR Inline submit — no page navigation, everything in background #5: Cloudflare Worker proxy → extra infrastructure to maintain
• PR Remove Cloudflare Worker, use client-side GitHub API #6: Client-side GitHub API with PAT → security anti-pattern (token exposed in page source)

We need to start fresh with a well-designed approach.

Who does this well?

Product	Pattern	Strengths	Weaknesses
DeepWiki (Devin)	URL swap: deepwiki.com/{owner}/{repo}	Progressive loading, pre-indexed 50K repos, instant for cached	Heavy backend, 30s-30min generation
pkg.go.dev	Auto-index + "Request" button	Clean UX, hybrid model	Requires Go proxy infrastructure
docs.rs	Auto-build on publish	Zero user friction	No on-demand generation, queue can be slow
GitIngest	Paste URL / URL swap: gitingest.com/{owner}/{repo}	Instant results, URL substitution	Ephemeral (no caching/permalinks)

Proposed Approach: URL-First Documentation (inspired by DeepWiki + pkg.go.dev)

Core Idea

The URL is the product. repos.supermodeltools.com/{owner}/{repo} either serves docs or tells you how to get them.

UX Flow

Scenario A — Docs exist (majority of traffic):

1. User visits repos.supermodeltools.com/facebook/react
2. Docs load instantly (static HTML on GitHub Pages CDN)
3. Done

Scenario B — Docs don't exist yet:

1. User visits repos.supermodeltools.com/facebook/react
2. Custom 404 page detects the URL pattern and shows a branded "landing" page:
   • Repo name + description (fetched client-side from GitHub API, no auth needed)
   • "This repo hasn't been documented yet"
   • "Generate Architecture Docs" button
3. User clicks "Generate" → opens a pre-filled GitHub Issue in a new tab:
   • Title: [Generate] facebook/react
   • Body: pre-filled with the repo URL
   • One-click submit (user needs GitHub account — fine for a developer tool)
4. Issue auto-triggers the auto-add-repo workflow
5. Workflow: validates repo → forks into org → sets up arch-docs → enables Pages → adds to repos.yaml
6. User gets notified on the GitHub Issue when complete (issue auto-closed with link)
7. Same URL now serves real docs

Why This Approach

1. Zero infrastructure — GitHub Pages + Actions only, no serverless functions, no tokens in client code
2. Shareable URLs — repos.supermodeltools.com/torvalds/linux works as a link whether docs exist or not
3. No security concerns — no API tokens exposed, no proxy needed
4. GitHub account required — acceptable for a developer-facing tool. This is actually a feature (prevents abuse)
5. Automatic discovery — sync-repos.yml cron finds org repos with arch-docs every 6 hours, so internal repos appear without anyone requesting them
6. Progressive enhancement — the 404 landing page can show repo metadata (stars, language, description) fetched from the public GitHub API, making it feel like a real page even before docs exist

Technical Implementation

1. URL Routing via Custom 404

GitHub Pages serves 404.html for all unmatched routes. We make this smart:

<!-- 404.html -->
<script>
  const path = window.location.pathname.split('/').filter(Boolean);
  if (path.length === 2) {
    // Looks like /{owner}/{repo} — show the "generate" landing page
    showRepoLanding(path[0], path[1]);
  } else {
    // Actual 404
    showNotFound();
  }
</script>

The landing page fetches repo metadata from the public GitHub API (no auth needed for public repos) and renders a branded page with the "Generate" button.

2. Pre-filled Issue Link

The "Generate" button links to:

https://github.com/supermodeltools/supermodeltools.github.io/issues/new?
  title=[Generate] {owner}/{repo}&
  body=Repository: https://github.com/{owner}/{repo}&
  labels=repo-request

No API calls, no tokens, no JavaScript fetch. Just a link.

3. Workflow: auto-add-repo.yml

Triggers on issues with repo-request label. Validates, forks, generates, deploys. (This was already built in PR #3 — we bring it back.)

4. Workflow: sync-repos.yml

Cron every 6 hours, discovers org repos with arch-docs that aren't on the homepage yet. (Also from PR #3.)

5. Homepage Search + Browse

The homepage at repos.supermodeltools.com/ keeps the existing search/browse UI for discovering documented repos. Add a prominent input field: "Paste any GitHub repo URL" → navigates to /{owner}/{repo} which either loads docs or shows the landing page.

Open Questions

1. Should the 404 landing page poll for completion? It could check every 30s if the docs URL returns 200, then auto-redirect. But generation takes 5-10 minutes, so this might be wasteful. Alternative: just say "Check back in a few minutes" and let the GitHub Issue notification handle it.

2. Rate limiting / abuse prevention: The GitHub Issue approach naturally limits abuse (requires account, visible in issue tracker). Should we add a cooldown check (e.g., don't show "Generate" if an open issue already exists for this repo)?

3. Should we pre-generate docs for the top N popular repos? DeepWiki pre-indexed 50K repos. We could batch-generate docs for popular repos to make the site immediately useful.

4. Per-repo pages architecture: Currently each repo's docs live on a separate GitHub Pages site (on the fork). Should we consolidate them under repos.supermodeltools.com/{owner}/{repo} using a build step, or keep them as separate sites linked from the index?

---

@claude please critique this plan. Consider: security implications, UX friction points, edge cases (private repos, archived repos, very large repos), scalability (what happens at 1000+ repos), and whether there's a simpler approach we're missing. Also evaluate whether the 404-based routing is the right pattern or if there's a better way to handle the "docs don't exist yet" state on GitHub Pages.

[coderabbitai]

🔗 Related PRs

#3 - Add 'Request a Repo' button and issue template [closed]
#5 - Inline submit — no page navigation, everything in background [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[jonathanpopham]

@claude Please critique this plan as a comment on this issue. Do NOT create a branch or PR. Just analyze and respond here with:

1. Security concerns
2. UX friction points
3. Edge cases we missed
4. Whether the 404-based routing is the right approach for GitHub Pages
5. Simpler alternatives we should consider
6. Your recommended approach

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[jonathanpopham]

@claude Critique this plan. Reply as a comment only — do not create branches or PRs.

[claude]

Claude finished @jonathanpopham's task in 2m 50s —— View job

---

Plan Critique

• Gather context (read codebase)
• Write critique

---

The overall approach is sound — URL-first routing via 404.html is the canonical GitHub Pages pattern and the GitHub Issue generation trigger is genuinely clever (zero infrastructure, abuse-resistant, auditable). Here's what I found after reading the codebase.

---

1. URL Schema Mismatch (Blocking Issue)

The current codebase uses /{repo-name}/ URLs, not /{owner}/{repo}/. In generate-index.go:398:

<a href="/{{pathEscape .Name}}/" class="card" ...>

And repos.yaml stores repos by name only (react, gin, flask). Supermodel's own repos don't have an upstream field at all, so there's no universal owner to derive from.

Moving to /{owner}/{repo} is a breaking schema change that migrates all 26 existing links. The plan needs to address this explicitly — either:

• Migrate: Update repos.yaml to store {owner}/{repo}, update the generator, add redirects from old URLs
• Don't migrate: Keep /{repo-name}/ for existing docs, use /{owner}/{repo} only for the 404 landing page (the two spaces don't collide)

Option B is simpler for an MVP but creates a URL inconsistency.

---

2. Security Concerns

GitHub API rate limits on the 404 page
The unauthenticated GitHub API allows 60 requests/hour per IP. A user in a corporate office who visits several undocumented repos could exhaust this for everyone on that IP. The 404 page should:

• Cache the API response in localStorage keyed by {owner}/{repo}
• Fail gracefully (still show the "Generate" button, just without the metadata)

XSS in the 404 page
window.location.pathname is attacker-controlled. Before using path segments to construct API URLs or inject into the DOM, every value needs encodeURIComponent() for URLs and proper DOM text node insertion (not innerHTML). This is easy to miss.

Workflow input validation
The auto-add-repo.yml triggers on any issue with the repo-request label. The workflow is the only gate. It must validate:

• The repo is public (private repos return 404 from public API — treat as invalid)
• The repo is not archived (archived: true in API response)
• The repo is not already in repos.yaml
• The repo URL matches github.com/{owner}/{repo} exactly (no path traversal, no URLs pointing at other hosts)
• The repo isn't a fork (probably — derivative works with same architecture aren't useful)
• The repo isn't over a size threshold (linux kernel has 1M+ files; arch-docs would time out)

Malformed issue URL in the proposal
The "Generate" button URL example in the issue body is malformed — {owner}/{repo}&body=... is missing title=. The correct form is:

https://github.com/supermodeltools/supermodeltools.github.io/issues/new?title=%5BGenerate%5D+{owner}%2F{repo}&body=Repository%3A+https%3A%2F%2Fgithub.com%2F{owner}%2F{repo}&labels=repo-request

All values must be encodeURIComponent()-encoded in the JS that constructs this.

---

3. UX Friction Points

The generation flow has 5 context switches
Visit URL → GitHub Issue tab opens → submit → close tab → come back later → check GitHub notification → return to URL. That's a lot of friction for what should feel like "press a button, come back tomorrow." Consider whether the button should say "Request docs" rather than "Generate" to set expectations.

No "already requested" state
Two users requesting the same repo will both see the Generate button and both create issues. The 404 page has no way to know an open issue already exists without an authenticated API call. The workflow needs deduplication (search for existing open issues with matching body before processing), but the page UX can't reflect this. At minimum, add client-side localStorage to show "You already requested this — check back soon" for repeat visitors.

5-10 minute generation with no in-page feedback
"Check back in a few minutes" is fine, but "a few minutes" and "5-10 minutes" are different. The page should set honest expectations and link directly to the created issue (possible since the button opens GitHub) so users can track progress there.

JS-only experience
If the 404 page JS fails or is blocked, users see a blank GitHub 404. A <noscript> fallback with a static message and a link to the GitHub repo would be minimal but good practice.

---

4. Edge Cases

Case	Issue
Private repo	GitHub API returns 404. Page falls through to "Actual 404" even though the URL looks like /{owner}/{repo}. Should detect API 404 and show "private or doesn't exist" message instead of generic 404.
Archived repo	API returns archived: true. Should show warning and either suppress or annotate the Generate button. Generating docs for a dead repo is a waste of Actions minutes.
Forked repo	API returns fork: true. Forks share architecture with upstream — probably not worth generating.
Very large repo	linux, chromium, llvm would timeout or OOM the arch-docs generator. Workflow needs a size gate (e.g., reject repos over 500MB or 50K files).
Repo renamed/deleted post-generation	The sync-repos.yml cron should detect 404s on upstream repos and either remove them or mark them stale.
Race conditions	Two concurrent issue submissions for the same repo. The workflow should lock (or check) before forking.
/{owner} path (one segment)	A URL like /facebook hits the 404 page and path.length === 1 — currently falls to "Actual 404" which is correct, but could be confusing.

---

5. The 404 Routing Question

It's the right approach for GitHub Pages. There's no better option given the hosting constraint. However:

SEO: Pages served via 404 return HTTP 404 status. Search engines won't index them. For a developer tool, this probably doesn't matter — but if you want repos.supermodeltools.com/facebook/react to appear in search results before docs exist, the 404 approach won't work. Alternative: build-time generation of stub "pending" pages for requested repos (these return 200, are indexable).

Simpler alternative for the homepage UX: Rather than relying solely on 404 routing for discovery, add a "Paste a GitHub URL" input directly on the homepage. Users who arrive at the index can request docs without needing to know the URL pattern. This complements (not replaces) the 404 approach.

---

6. Open Questions — My Takes

1. Should the 404 page poll? No. A 30s polling loop that runs for 10 minutes is wasteful and annoying. Set expectations ("docs take 5-10 minutes") and link to the GitHub issue. Let GitHub's notification system do the work.

2. Rate limiting / abuse? The GitHub account requirement is sufficient for an MVP. Add a cooldown check in the workflow (search for existing issue with same repo in title) to prevent duplicate processing.

3. Pre-generate popular repos? Yes, this is the highest-leverage action to make the site immediately useful at launch. Even 20-30 top repos (next.js, django, rails, spring-boot) would make the site feel real rather than a demo.

4. Per-repo pages architecture? Keep them as separate sites for now. Consolidating under repos.supermodeltools.com/{owner}/{repo} is a larger architectural change (requires a unified build that pulls from all forked repos) and can come later.

---

Recommended Approach

The plan is solid. Suggested priority order:

1. Decide on URL schema (/{name} vs /{owner}/{repo}) before writing any code — this affects everything else
2. Build the 404 page with proper XSS protection, graceful API failure handling, and clear copy
3. Add homepage input — low effort, high value, doesn't require 404 routing knowledge
4. Bring back auto-add-repo.yml with the additional validation gates listed above (archived, fork, size, dedup)
5. Pre-generate ~30 popular repos to give the site immediate credibility
6. Skip polling — GitHub notifications are sufficient

The biggest risk in the plan as written is the URL schema migration, which is currently unaddressed. Everything else is solvable in implementation.

[jonathanpopham]

@claude Acknowledge this message with a one-line reply to confirm the code factory is operational.

[claude]

Claude finished @jonathanpopham's task in 9s —— View job

---

Code factory is operational. ✓