Skip to content

CLAUDE.md

Latest commit

 

History

History
53 lines (40 loc) · 3.61 KB

CLAUDE.md

File metadata and controls

53 lines (40 loc) · 3.61 KB
Raw

CLAUDE.md

Project

GitHub-starred-repos dashboard — v0.2. Static SPA + Serverless Search API on Vercel. Repo = single source of truth. No Vercel CLI deploys — pushing to main triggers the deploy.

No GitHub releases. No release tags. Version tracked in CHANGELOG.md only.

Data pipeline

  • fetch_stars.py — pulls all starred repos from GitHub API, categorizes by keyword (word-boundary matched), writes repos_output.json with pushed_at and archived
  • build_site.py — bakes repos_output.json into index.html (SEO, project matcher, FAQ, view toggle) + llms.txt + llms-full.txt + per-category llms-*.txt + sitemap.xml. Run after every fetch_stars.py
  • generate_assets.py — regenerates icons/, favicon.ico, og-image.png, manifest.webmanifest from design tokens (PIL). Only re-run when brand changes
  • api/search.js — Serverless REST search endpoint for AI agents, tools, and MCP servers (CORS enabled)
  • .github/workflows/sync-stars.yml — runs weekly (cron 0 0 * * 0 on Sundays) + manual workflow_dispatch (1–7 days), runs fetch + build, commits fresh repos_output.json + generated site files if changed. Uses ephemeral secrets.GITHUB_TOKEN
  • Site renders repos_output.json — no backend database

Key files

File Role
index.html Generated by build_site.py — do not hand-edit. Shell + SEO, project matcher UI, FAQ, category cloud
app.js SPA: fetch → profile → metrics → category tabs → lang filter → sort → grid/compact view → project relevance matcher → local bookmarks
style.css Warm amber "Bloom" aura theme (Hallmark), Inter Tight/Inter/JetBrains Mono/Instrument Serif, OKLCH tokens. Styles for cards, compact rows, project matcher drawer, toast notifications, ambient blooms
api/search.js Vercel Edge/Serverless function for AI agents to query repos with query, category, lang, limit filters
vercel.json cleanUrls, security headers, caching for repos_output.json, /api/*, /llms*.txt endpoints
repos_output.json Generated — never hand-edit. Structure: username/total_repos/generated_at/profile/repos[]
llms.txt Top 100 repos + Topic Taxonomy + Category Manifest for AI search engines
llms-full.txt All repos + metadata
llms-*.txt Category-specific LLM endpoints (llms-ai-agents.txt, llms-dev-tools.txt, etc.)
sitemap.xml Generated by build_site.py with current <lastmod> and all LLM endpoints

Conventions

  • app.js: all repo-derived strings go through escapeHTML() before template insertion. repo.url in href too — GitHub API is trusted, keep it that way
  • No console.log in production code
  • Git: HTTPS via gh credential manager. Identity: 272530059+AkashPriyadarshii@users.noreply.github.com
  • .omc/, .codegraph/ are local tooling junk — never commit (both in .gitignore)
  • No GitHub releases — version is tracked in CHANGELOG.md only

Verify after edits

node --check app.js api/search.js                           # JS syntax
python -m py_compile fetch_stars.py build_site.py generate_assets.py   # Python syntax
python -c "import json; json.load(open('repos_output.json'))"  # data parses
python build_site.py                                        # regenerate site after data changes

Known behavior

  • Live site can lag repo: Vercel edge-caches repos_output.json up to max-age + SWR window. A push redeploys, but a cached JSON may serve up to ~1h old — not "real time"
  • Cached JSON age on Vercel shows as X-Vercel-Cache: HIT + Age header. Diagnose staleness with curl -sI .../repos_output.json