RepoRelay

A GitHub repo recommender. Give it a repo, get back similar repos.

No ML training. No user data. Postgres + pgvector + Gemini embeddings (512-dim).

visit the site

fastapi/fastapi  →  pallets/flask, django/django, psf/requests, encode/starlette ...

---

What's here

• 5-stage hybrid recommender — SQL filter + pgvector ANN + full-text search + keyword overlap → 12 weighted features → score → rerank for diversity

• Gemini embeddings (512-dim) — description embeddings as primary signal, with README embeddings for source repos

• Keyword-based semantic search — domain keywords extracted from descriptions + READMEs, matched via GIN ARRAY overlap and tsvector full-text search. Covers cold repos with no embeddings instantly

• Proxy-first architecture — new repos get instant results via keyword + full-text search; Gemini embedding runs in background for next visit

• Relevance feedback — "Show more like these" picks repos similar to ones you've liked, merges results across multiple sources

• Seed-based variation — deterministic jittering of scoring weights; same seed = same results

• Purpose extraction — extracts project purpose from READMEs when description is sparse

• Topic inference — 260+ topic vocabulary inferred from README text for repos with sparse GitHub topics

• Dual GitHub token auto-rotation — transparent switch on rate limit, 10,000 req/hr combined

• Keyword extraction — 20% of corpus (10K+ repos) has domain keywords extracted, powering keyword_match scoring feature

• Trending signal — scrapes github.com/trending daily to surface viral repos

• Web UI — Astro 5 + vanilla JS, dark/light theme, glass cards over a generative commit-graph art backdrop

• 12 grid-art patterns — aurora, ocean, stars, peaks, gems, cracks, ripples, forest, matrix, comb, bloom, contour — pickable from the nav, persists per user

• explore topics explore over 70+ topics

  

→ Architecture & data flow · → Deploy notes · → CLI reference · → Indexing guide · → Improvements

---

Quickstart

# 1. Clone & install
git clone https://github.com/ramsterr/RepoRELAY.git && cd RepoRELAY
just sync

# 2. Set up .env
echo 'DATABASE_URL=postgresql+psycopg://reporelay:reporelay@localhost:5439/reporelay' > .env
echo 'GITHUB_TOKEN=ghp_your_token' >> .env
echo 'EMBEDDING_API=local' >> .env

# 3. Start Postgres & run migrations
just up && just migrate

# 4. Save some repos
just mvp save fastapi/fastapi
just mvp save django/django
just mvp save pallets/flask

# 5. Get recommendations
just mvp recommend fastapi/fastapi

Prerequisites: Docker, Python 3.12+, uv, Node.js 20+, pnpm

For production (Render free tier, no local model): set EMBEDDING_API=gemini and GEMINI_API_KEY.

---

Run it

just api          # API server on :8001
just site         # Web UI on :4321  (Astro dev — first request compiles, then fast)
just site-fast    # Built site on :4321  (prebuilt via Node adapter, always fast)
just dev          # Both at once

---

API

Endpoint	Description
GET /health	Liveness check
GET /popular?limit=N&topic=X	Top repos by stars, optionally filtered by topic
GET /topics?limit=N	Top topics in the database
GET /recommend?repo=owner/name&limit=N&seed=N&tags=a,b	Ranked recommendations for a repo
GET /explore?seed=N&limit=N	Random repo + its recommendations
POST /recommend/more	Show more repos like selected candidates (relevance feedback)

Params:

• limit — result count (default 10, max 50)
• seed — integer, gives deterministic variation in the ranking (same seed = same order)
• tags — comma-separated list; embeds the tag text and matches semantically against candidate descriptions

Response shape (/recommend):

{
  "groups": [
    {
      "name": "description_cosine_sim",
      "label": "Description similarity",
      "icon": "📝",
      "repos": [
        {
          "full_name": "pallets/flask",
          "description": "The Python micro framework for building web applications.",
          "language": "Python",
          "stars": 67000,
          "score": 0.84,
          "features": {
            "language_match": 1.0,
            "topic_overlap": 0.6,
            "description_cosine_sim": 0.78,
            "dep_overlap": 0.3,
            "star_ratio": 0.95,
            "trending_boost": 0.1
          }
        }
      ]
    }
  ],
  "flat_repos": ["same repos flattened for convenience"]
}

---

CLI

just mvp save owner/name           # fetch + embed + store a repo
just mvp recommend owner/name      # get recommendations (CLI)
just mvp count                     # how many repos in the DB
just mvp seed --per-language 1000 --languages python,rust  # bulk-index by language
just mvp seed-topics --per-topic 200              # bulk-index by topic (260+ topics)
just mvp embed --limit 1000                      # embed repos missing vectors
just mvp extract-keywords --limit 5000            # extract domain keywords from descriptions
just mvp trending --since daily                  # scrape github.com/trending
just mvp infer-topics                            # backfill inferred topics from READMEs
just mvp register-webhooks                       # register GitHub push webhooks on all repos
just mvp explore                                 # random repo + its recs

---

How it works

GitHub API ──► Postgres + pgvector + tsvector ──► Candidates ──► Features ──► Score ──► Rerank ──► Results
  (fetch)      (store + ANN + full-text)           (150-250)    (12 floats) (1 float)  (diverse)  (top N, grouped)

1. Fetch — repo metadata + README from GitHub API (dual token auto-rotation)
2. Embed — description → 512-dim vector via Gemini gemini-embedding-001 (or local BAAI/bge-small-en-v1.5 with MRL truncation)
3. Candidates — SQL filter (language/topics) ∪ pgvector ANN ∪ full-text search ∪ keyword overlap, deduplicated
4. Features — 12 signals: description cosine sim, README vs desc cosine sim, README topic overlap, keyword match, keyword-topic match, topic overlap, language match, language diversity, dep overlap, star ratio, quality signal, trending boost
5. Score — weighted sum with adaptive redistribution (hand-tuned, no training)
6. Rerank — drop same-owner, enforce one-per-owner diversity, group by dominant signal

→ Detailed architecture

---

Tech

Layer	Stack
Embedding	Gemini gemini-embedding-001 (512 dims via MRL, production) / BAAI/bge-small-en-v1.5 (384 dims, local dev)
Database	Postgres 16 + pgvector (HNSW index) + tsvector (full-text) + GIN (keyword arrays)
API	FastAPI (async)
Frontend	Astro 5 (static, Vercel)
Packages	uv (Python) · pnpm (Node)
Deploy	Vercel (frontend) + Render (API)
Cron	GitHub Actions (embed, seed, trending — every 30 min)

---

Repo layout

.
├── apps/
│   ├── site/                     # Astro frontend (Vercel)
│   │   └── src/
│   │       ├── layouts/Base.astro    # grid art, theme toggle, art picker
│   │       ├── pages/               # index, explore, repo
│   │       └── styles/global.css
│   └── mvp_api/                  # FastAPI service (Render)
│       └── src/reporelay_mvp_api/
│           ├── main.py               # endpoints + show-more + cache
│           └── webhooks.py           # GitHub push handler
├── packages/
│   └── mvp/                      # core library (shared between CLI + API)
│       └── src/reporelay_mvp/
│           ├── recommend.py          # 5-stage pipeline + proxy cold-repo flow
│           ├── candidates.py         # SQL filter + pgvector ANN
│           ├── features.py           # 12 signal extractors + IDF-weighted topics
│           ├── score.py              # adaptive weighted sum (77% semantic)
│           ├── rerank.py             # diversity rules
│           ├── embedding.py          # Gemini + local + none (260 lines)
│           ├── feedback.py           # show-more: merge + more_like_these
│           ├── keyword_extractor.py  # domain keyword extraction from desc+README
│           ├── purpose.py            # purpose extraction from READMEs
│           ├── topic_inference.py    # 260+ topic vocabulary inference
│           ├── seed_topics.py        # uniform + weighted bulk indexing
│           ├── github.py             # dual token + httpx client
│           ├── trending.py           # github.com/trending scraper
│           ├── seed.py               # bulk indexer by language
│           ├── embed_pass.py         # backfill missing embeddings
│           └── cli.py                # typer CLI
├── .github/workflows/
│   ├── embed.yml                # cron: embed 3000 repos every 30 min
│   ├── seed.yml                 # cron: seed topics every 6 hours
│   ├── trending.yml             # cron: scrape trending daily
│   └── ping.yml                 # cron: keep Render container warm
├── infra/
│   └── docker-compose.yml       # local Postgres + pgvector
├── Dockerfile.api               # Render API image
├── render.yaml                  # Render service config
├── pyproject.toml               # uv workspace
└── justfile                     # task runner

why i made this site? and my thinking philosophy behind it

mostly the reason was personal use , i actually like to explore a lot....also another reason was i felt that github explore feature was kind of blinding me from what i dont know ,

for example you'd never search something like 'CRDTs (Conflict-free Replicated Data Types) ' unless you know it exists , or someone told about it to you.

i actually use my own repo pretty regularly now , i would usually get a repo and paste its url here to see similar implementations of that thing. So it helps me get better alternatives and somewhat similar to what im specifically looking for.

another reason was also that i would just paste some Free resource (can be movies,media ,news or other day to day stuff) and get more like them. so i use my repo to free load a lot of good stuff thanks to open-source legions.

i belive that github is actually a treasure box which people dont seem to use it to its fullest...you can literally find anything for free on github that you'd have to pay otherwise.

also i added multiple themes so that i dont get bored of the site , you can find a few of them below:

matrix

coral

desert

waves

gems

sakura

---

License

MIT