📦 npmatch

Find the right npm package - describe what you need, get AI-powered recommendations grounded in real registry data.

Live Demo · Backend API

✨ What it does

Searching npm is painful. npmatch lets you describe what you're trying to build in plain English, and returns ranked package recommendations with tradeoff explanations - powered by semantic search over real npm data and streamed LLM synthesis.

• 🔍 Semantic search - finds packages by meaning, not just keywords
• ⚡ Streaming UX - recommendations stream in token by token as they're generated
• 📊 Grounded results - LLM only recommends from retrieved real packages, no hallucination
• 🎯 Filter by framework and priorities - React vs Node, bundle size vs popularity vs TypeScript support

🏗️ Architecture

Browser
↓
Next.js API Route (/api/search) ← proxy layer, hides backend URL + secrets
↓
FastAPI backend
↓ ↓ ↓
Qdrant Postgres OpenAI
(vec) (metadata) (gpt-4o)

RAG pipeline:

1. User query is embedded via text-embedding-3-small
2. Qdrant returns top 6 semantically similar package names
3. Postgres is joined for full metadata (description, keywords, version)
4. Retrieved packages + query are passed to GPT-4o as context
5. LLM synthesizes a recommendation - streamed back to the browser via SSE

The LLM never guesses from training memory. It only reasons over the retrieved packages, keeping recommendations verifiable and current.

🛠️ Stack

Layer	Tech
Frontend	Next.js 15, TypeScript, HeroUI v3, Tailwind CSS v4
Backend	FastAPI, Python 3.13, uv
LLM	OpenAI GPT-4o (streaming)
Embeddings	OpenAI text-embedding-3-small
Vector DB	Qdrant
Metadata DB	Postgres (asyncpg)
Ingestion	Node.js, TypeScript
Infra	AWS ECS Fargate, ECR, ALB, Terraform, Vercel, Supabase, Qdrant Cloud, Docker
CI/CD	GitHub Actions

📁 Project structure

npmatch/
├── README.md
├── docker-compose.yml # local full-stack dev
│
├── ingestion/ # Node.js - data pipeline
│ ├── src/
│ │ ├── fetch.ts # pulls top packages
│ │ ├── embed.ts # OpenAI embeddings
│ │ └── upsert.ts # pushes vectors to DB
│ └── Dockerfile
│
├── backend/ # FastAPI
│ ├── app/
│ │ ├── main.py # routes, middleware, CORS, rate limiting
│ │ ├── search.py # embed query + vector search
│ │ ├── llm.py # GPT-4o streaming + prompt construction
│ │ └── models.py # Pydantic request/response models
│ └── Dockerfile
│
├── frontend/ # Next.js
│ ├── app/
│ │ ├── page.tsx
│ │ └── api/
│ │ └── search/ # SSE proxy to backend
│ │ ├── route.ts
│ │ └── health/ # health check proxy
│ │ └── route.ts
│ ├── components/
│ │ ├── SearchForm.tsx
│ │ ├── PackageCard.tsx
│ │ ├── StatusStates.tsx
│ │ └── LlmPanel.tsx
│ └── hooks/
│ └── useSearch.ts # SSE streaming logic
│
└── infra/ # Terraform
├── main.tf
├── variables.tf
├── outputs.tf
└── modules/
├── ecs/
└── networking/

🔌 API

POST /api/search

Streams package recommendations as SSE.

Request

{
"query": "parse markdown with syntax highlighting in React",
"framework": "react",
"priorities": ["bundle size", "TypeScript support"]
}

SSE stream format

event: packages
data: [{"name": "...", "version": "...", "description": "...", "npm_url": "..."}]
data: chunk chunk chunk... ← LLM markdown, \n escaped as \\n
event: done
data: [DONE]

GET /health

Returns backend status. Polled by frontend every 60s with animated signal indicator.

🗄️ Data pipeline

npm's search API is capped at 250 results - not enough for meaningful semantic search. Instead:

1. Fetch - downloads the top 10,000 most popular npm packages from npm-rank as a JSON file
2. Clean - filters out packages missing a name or description, deduplicates by package name, and strips irrelevant fields (author, sponsors, maintainers)
3. Embed - formats each package as "{name}: {description}. keywords: {keywords}" and batch-embeds via OpenAI text-embedding-3-small (batches of 100)
4. Upsert - pushes vectors into Qdrant (payload: name only) and metadata (name, description, keywords, version) into Postgres. Idempotent - safe to re-run, Qdrant upserts overwrite by deterministic UUID, Postgres upserts use ON CONFLICT (name) DO UPDATE

☁️ Infrastructure

Live demo (always-on, zero cost)

Vercel - Next.js frontend + FastAPI backend (serverless)
Qdrant Cloud - vector search (free tier)
Supabase - Postgres + pgvector (free tier)

The live demo runs entirely on free tiers - no ongoing infrastructure cost.

🔧 A self-hosted VPS backend (Oracle Cloud Always Free) is planned as an alternative to Vercel's serverless backend.

AWS (portfolio showcase)

Terraform configuration in /infra provisions a production-grade AWS deployment:

ECR
npmatch-frontend
npmatch-backend
npmatch-ingestion
ECS Fargate
frontend service - behind ALB
backend service - behind ALB with HTTPS termination
qdrant service - internal, EFS for persistent storage
ingestion scheduled task - weekly via EventBridge
ALB
HTTPS termination
public + private subnets, security groups

💡 To spin up the full AWS deployment: terraform apply in /infra. To tear it down: terraform destroy.

🚀 Running locally

Prerequisites: Docker, Node.js 20+, Python 3.13+, OpenAI API key

Full stack with Docker Compose

# clone the repo
git clone https://github.com/kodingkin/npmatch
cd npmatch
# add environment variables
cp backend/.env.example backend/.env
# fill in OPENAI_API_KEY
cp frontend/.env.example frontend/.env
# start all services (frontend, backend, Qdrant, Postgres)
docker compose -f docker-compose.yml up -d --build

Frontend: http://localhost:3000 Backend: http://localhost:8000

🌱 Ingestion (seed the vector DB)

cd ingestion
npm install
cp .env.example .env
# fill in OPENAI_API_KEY
tsx src/index.ts

🎯 Design decisions

Why RAG instead of asking GPT-4o directly? LLMs hallucinate package names and versions. By retrieving real packages from the vector database first and passing them as context, the LLM only reasons over verified data - recommendations are grounded and verifiable.

Why SSE over WebSockets? Streaming is one-directional (server → client). SSE is simpler, stateless, and works over standard HTTP - no connection management overhead.

Why Next.js API route as proxy? Keeps the backend URL off the client entirely. The browser never talks to FastAPI directly.

Why Qdrant + Postgres over a single vector store? Pinecone bundles vectors and metadata together - simple, but not how production systems are typically designed. Splitting vector search (Qdrant) from structured metadata (Postgres) reflects real-world architecture patterns and keeps each store doing what it does best. Postgres also enables hybrid search combining vector similarity with full-text search for improved retrieval quality.

Why text-embedding-3-small? Good balance of semantic quality and cost at this scale. Upgrade path to text-embedding-3-large is a one-line change.

📋 Known limitations

• Ingestion is a point-in-time snapshot - very new packages may not appear until the next weekly refresh
• No re-ranking step - production would add a cross-encoder re-ranker to improve retrieval precision
• No evaluation pipeline - answer faithfulness and retrieval quality are not measured automatically
• Rate limited to 2 requests/minute per IP

👤 Author

Built as a portfolio project demonstrating full-stack AI integration - RAG pipeline, streaming UX, and AWS infrastructure with Terraform.