Landing + inline search
Hero, how-it-works, features, use cases, and a search entry that deep-links to /search?q=.
NeedVisitors should understand the pipeline before waiting on AI.
ValueClear product story and fast first query.
ProjectsCase StudyAI Developer Tool2026
Case Study
GitSearch AI
Describe what you want to build—AI searches GitHub, reads READMEs, and returns ranked repos with scores, strengths, and gaps.
Natural-language GitHub discovery—describe what you want to build; AI searches repos, reads READMEs, and returns a ranked shortlist.
GitSearch AI turns a project brief into GitHub keywords, runs multi-strategy search, enriches candidates with READMEs, and scores matches with strengths, gaps, and tech tags—no accounts, no database, dual Gemini/OpenAI providers.
- Industry
- Developer tools · Open-source discovery
- Category
- AI product · GitHub search
- Role
- Full Stack Product Engineer — product, AI pipeline, GitHub orchestration, and UI end to end
- Timeline
- 2026
- Status
- MVP product build
- Stack
- Next.js · TypeScript · Tailwind · Gemini / OpenAI · GitHub REST · NDJSON streaming
Executive Overview
GitSearch AI replaces manual GitHub keyword digging. Developers paste a build brief; the app extracts short search keywords, queries GitHub, demotes curated list pollution, reads READMEs, and returns a top-five ranked shortlist with match scores.
The experience is free and account-free: a marketing landing plus /search with live streaming progress (understanding → keywords → searching → READMEs → evaluating → ranking).
Architecture is a server-side search orchestrator behind POST /api/search. AI is provider-abstracted (Gemini or OpenAI), GitHub search uses staged strategies, and evaluation is batched to control latency and cost.
There is no auth or database in the MVP—intentional scope so the case study centers on AI + search quality, streaming UX, and typed failure modes.
Business Problem
Existing workflow
Developers hunt starters and libraries by guessing GitHub keywords, scrolling awesome-lists, and skimming READMEs one tab at a time—slow and noisy when the intent is a full project brief.
Pain points
- Natural-language intent does not map cleanly to GitHub’s AND keyword search.
- Awesome-lists and curated collections dominate search results but are not buildable starters.
- README skim is tedious across dozens of candidates.
- Long AI pipelines feel broken without progress feedback.
- Provider lock-in (one LLM vendor) is risky for cost and availability.
Why it matters
Choosing the wrong repo wastes days. A short, scored shortlist with strengths and gaps turns discovery into a decision—not another search rabbit hole.
Solution
GitSearch AI runs a deliberate pipeline from brief to ranked repos:
Intent extraction
NL brief → short GitHub keywords (2–4 words × 3) plus checkable requirements via structured AI JSON.
Multi-strategy GitHub search
Strict exclusions → broader queries → name-only fallbacks; dedupe across keyword passes.
Heuristic shortlist
Pre-filter candidates and demote curated/awesome lists before expensive README + AI work.
README enrichment + AI scoring
Concurrent README fetch, batched evaluation for matchScore, tech, strengths, gaps, and recommendation reason.
Streaming progress UX
NDJSON events so the UI shows understanding → ranking instead of a silent 60s wait.
Faster open-source discovery with a transparent pipeline, ranked matches that prefer real projects over list repos, and a dual-provider AI core ready to swap models.
Core Features
Discovery experience
Results page
Empty tips state, live progress steps, ranked RepositoryCards with score, summary, strengths, gaps, tech, stars.
NeedTrust comes from seeing why a repo ranked.
ValueDecisions, not just links.
Retry & error states
Typed Validation / GitHub / AI / RateLimit errors surfaced with retry.
NeedUpstream APIs fail; the UI must recover gracefully.
ValueFewer abandoned searches.
AI + search pipeline
Keyword extraction
Structured completion turns a brief into short GitHub-friendly keywords and requirements.
NeedLong phrases break GitHub AND search.
ValueHigher recall without noise queries.
GitHub multi-strategy search
Parallel keyword searches with exclusion stages and fallback query builders.
NeedOne query shape is not enough across domains.
ValueBetter candidate pools for evaluation.
List pollution control
Heuristics and scoring prompts demote awesome-lists / curated collections (score 0–15).
NeedLists look popular but are not starters.
ValueShortlists favor buildable repos.
Batch README evaluation
Cap candidates, truncate READMEs, evaluate in batches with concurrency limits.
NeedLatency and token cost explode without caps.
ValueUseful answers within the 60s route budget.
Platform choices
Dual AI providers
Unified createStructuredCompletion for Gemini or OpenAI via env (model + key).
NeedCost and availability should not lock the product to one vendor.
ValueSwap providers without rewriting the orchestrator.
NDJSON streaming API
POST /api/search streams progress and complete/error events.
NeedMulti-step AI work needs visible progress.
ValuePerceived performance and clearer failures.
Stateless MVP
No auth or database—each search is a self-contained orchestration.
NeedShip discovery quality before accounts and quotas.
ValueFast iteration on ranking quality.
User Journey
Developer → Ranked shortlist
- 01
Describes a project brief on landing or /search
- 02
API extracts keywords and requirements
- 03
GitHub search runs multi-strategy queries
- 04
Heuristics select top candidates
- 05
READMEs fetch concurrently
- 06
AI scores and ranks top 5
- 07
Developer opens the best GitHub match
Progress-aware wait
- 01
Client opens NDJSON stream
- 02
UI advances through understanding → keywords → searching → READMEs → evaluating → ranking
- 03
Complete event renders RepositoryCards
- 04
On typed error, UI shows retry path
Technical Highlights
Search orchestrator
Server-side pipeline owns keyword AI → GitHub → heuristic select → README → batch evaluate → filter/sort.
Business valueOne place to tune quality, cost, and timeouts.
Provider abstraction
Gemini and OpenAI share a structured JSON completion interface with model fallbacks and retries.
Business valueOperate through vendor limits without rewriting features.
GitHub query craft
Short keywords, staged exclusions, and demotion of curated lists before and during scoring.
Business valueResults feel like starters, not bookmark collections.
Cost/latency caps
Max 8 candidates, truncated READMEs, batch size 4, concurrency 3, batch delay, route maxDuration 60s.
Business valuePredictable spend and completable requests.
Streaming UX
NDJSON progress events mapped by useRepositorySearch into step UI.
Business valueUsers stay with the search instead of bouncing.
Typed error surface
Validation, GitHub, AI, and RateLimit errors carry codes for the client stream.
Business valueActionable failures instead of a generic timeout.
Challenges & Solutions
| Challenge | Solution |
|---|---|
| Natural-language briefs produced noisy GitHub queries that returned lists and weak matches. | AI keyword extraction into short phrases plus multi-strategy search and list demotion. |
| Evaluating every search hit with full READMEs was too slow and expensive. | Heuristic shortlist, truncated READMEs, batched AI evaluation, and concurrency limits. |
| A single LLM vendor created cost and availability risk. | Provider-abstracted structured completions with env-selected Gemini or OpenAI. |
| Multi-step pipelines felt broken during a long silent wait. | NDJSON streaming progress steps in the search UI. |
| Accounts and caching would have delayed learning whether ranking quality worked. | Ship a stateless MVP; roadmap Redis cache, queues, embeddings, and quotas later. |
Tech Stack
- Frontend
- Next.js 16 App Router, React 19, TypeScript, Tailwind CSS v4, Geist
- API
- Route Handler POST /api/search — NDJSON stream, maxDuration 60s
- AI
- Google Gemini or OpenAI — structured JSON keyword extraction & repo evaluation
- External APIs
- GitHub REST Search + raw README fetch
- Architecture
- features/search → services/{ai,github,search} → lib/utils/types
- Auth / DB
- None in MVP (stateless)
Project Gallery
Recommended capture order for the case-study gallery.
- 01Landing — hero and product story
- 02Landing — how it works
- 03Search empty state — tips
- 04Search — streaming progress steps
- 05Results — ranked RepositoryCards
- 06Card detail — score, strengths, gaps, tech tags
- 07Error / retry state
- 08Mobile — search and results
Key Learnings
Product
For discovery tools, a ranked shortlist with strengths and gaps beats dumping fifty GitHub links.
Engineering
Cap the AI surface area early—candidate limits and batching decide whether the product feels instant or broken.
Architecture
A provider interface for structured completions keeps the orchestrator stable when models change.
Search quality
Demoting awesome-lists is a product feature, not a footnote—popularity without buildability wastes trust.
Future Improvements
| Priority | Improvement | Business value |
|---|---|---|
| High | Redis (or similar) cache for repeated briefs and GitHub/README payloads | Lower latency and AI cost on common queries. |
| High | Background jobs (BullMQ / Inngest) for heavier evaluation paths | Room for deeper analysis without route timeouts. |
| Medium | Embedding-assisted ranking alongside LLM scores | Better semantic fit for vague briefs. |
| Medium | Light quotas / abuse controls without full accounts | Protect GitHub and AI budgets as traffic grows. |
| Low | Saved shortlists and compare mode | Help builders decide across two or three finalists. |
Building an AI workflow on messy real-world APIs?
GitSearch AI is a case study in intent → search → evaluate pipelines—provider abstraction, streaming UX, and ranking quality without a heavy backend. If you need similar craft on a developer tool, start a conversation.
Start a conversationOptional technical notes
How the pipeline stays fast enough to feel useful while still reading real READMEs.
Orchestrator as product core
UI and hooks stay thin. Quality lives in search-orchestrator: keyword AI, GitHub client, heuristic selectTopCandidates, concurrent README fetch, and batched evaluation.
That separation makes it possible to tune ranking without rewriting the landing or card components.
Why demote lists
Awesome-lists rank well on stars and keywords but fail as “what should I build on.” Heuristics and scoring prompts both push them down so the shortlist prefers implementable repos.
Stateless by design
Skipping auth and DB kept the MVP focused on whether the AI + GitHub loop works. Caching, queues, embeddings, and quotas are documented next steps once quality is proven.
Role
Full Stack Product Engineer
Client
Personal product / AI developer tool
Date
2026
Collaborators
Solo build
Next Project
Universal Cloud Saver
View next