Turn customer reviews into product decisions — in under 60 seconds.

Live app · Try sample data · Report an issue

In one sentence: ReviewLens accepts a CSV of product reviews, runs an embeddings → clustering → LLM summarization pipeline, and delivers a stakeholder-ready insight report with PDF/CSV export and password-protected sharing.

1. Upload — Drop a CSV or use Try sample data. Columns auto-detected (review, rating, author, date).
2. Embed — Each review → 1536-dim vector (text-embedding-3-small), batched in groups of 100 with 429 retry.
3. Cluster — k-means (k = max(2, min(8, round(n / 15))), k-means++ init) groups similar feedback.
4. Summarize — gpt-4o-mini labels each cluster (theme, description, sentiment) + one executive summary.
5. Report — Dashboard with sentiment charts, complaint/praise cards, export menu, and shareable URL.

Live demo path: Sign in → /analyze → Try sample data → dashboard → Share → copy link.

• Reduced duplicate pipeline runs in concurrent requests, measured by zero double-processing on the same session, by atomically claiming jobs with updateMany WHERE status = PENDING.
• Kept stakeholder handoff friction near zero, measured by view-only share links requiring no login, by shipping password/expiry gates with scrypt hashing and HMAC-signed httpOnly cookies (12h).
• Maintained release confidence as features grew, measured by 93 passing unit tests and GitHub Actions CI on every push to main, by testing CSV detection, validation, share crypto, and API contracts without a live database in CI.
• Chose share-first collaboration over email invites, measured by zero custom-domain email dependencies on Vercel, by deferring team-inbox UI while shipping PDF/CSV export and mailto: share drafts.
• Made ingestion flexible without brittle schemas, measured by automatic column mapping across common CSV formats, by building header-detection and paste-to-review parsers with dedicated test coverage.

Reviews (DB)
    │
    ▼
Embeddings         text-embedding-3-small · batches of 100 · retry on 429
    │
    ▼
k-means clustering k = max(2, min(8, round(n / 15))) · k-means++ init
    │
    ▼
Theme summarization gpt-4o-mini · one call per cluster (parallel) · JSON mode
    │
    ▼
Executive summary  gpt-4o-mini · one call across all themes
    │
    ▼
Persist            AnalysisResult (JSON columns) · AnalysisSession → COMPLETED

Triggered via POST /api/analysis/[slug]/process. Pipeline logs include requestId, sessionId, userId, stage, and OpenAI totalTokens. Completed runs persist processingMs on AnalysisResult.

Reproducible metrics from the bundled demo CSV (public/samples/product-reviews.csv) — 12 reviews, 2 clusters (k = max(2, round(n / 15))).

Representative themes produced (cluster labels vary slightly run-to-run; sentiment direction stable):

Reproduce metrics locally:

npx tsx scripts/benchmark-sample.ts --estimate-only   # offline — no API key
npx tsx --env-file=.env.local scripts/benchmark-sample.ts   # live pipeline + token usage

Scale intuition: At $0.0004 per 12-review run, a 500-review upload (max supported) costs roughly ~$0.02 in API spend — dominated by embedding tokens, not clustering CPU.

• Magic-link sign-in at /login (JWT sessions, edge-safe middleware)
• /analyze and /sessions require authentication; analyses scoped to User.id
• Dev mode: without RESEND_API_KEY, magic links print to the terminal

• Copy link — works on any Vercel URL
• Email draft — pre-filled mailto: (no API keys required)
• Password — scrypt-hashed; viewers unlock via HMAC-signed httpOnly cookie (12h)
• Expiry — 1 / 7 / 30 days or never
• Analysis owner always bypasses gates

• PDF — branded report (summary, sentiment, themes), client-side via lazy-loaded jspdf
• Summary CSV — themes + sentiment + executive summary
• Raw reviews CSV — streamed from API, gated by same share rules as dashboard

git clone https://github.com/Arlikhozhaev/ReviewLens.git
cd reviewlens
npm install
cp .env.example .env.local
# Required: DATABASE_URL, DIRECT_URL, OPENAI_API_KEY, AUTH_SECRET
# Optional: RESEND_API_KEY, UPSTASH_*, INNGEST_*, SENTRY_*

npx prisma migrate deploy
npx prisma generate
npm run dev

Open http://localhost:3000.

See .env.example. Key variables:

npx inngest-cli dev -u http://localhost:3000/api/inngest

npm test          # 93 Vitest unit tests
npm run test:watch
npm run test:e2e  # 4 Playwright specs (golden path + auth gating)

CI (.github/workflows/ci.yml) on every push/PR to main:

1. verify — ESLint, tsc --noEmit, Vitest (no live DB/network), production build
2. e2e — Postgres service + prisma migrate deploy, Playwright (Chromium) with placeholder env; API routes mocked in specs. Trace + HTML report uploaded on failure.

E2E setup:

npx playwright install   # first run only
npm run test:e2e

• auth.setup.ts — signed session cookie for authed specs
• golden-path.spec.ts — upload → preview → submit (mocks create/process/status APIs)
• auth-redirect.spec.ts — middleware gating without DB

Architecture: see docs/ARCHITECTURE.md for C4 context, request flows, ADRs, and failure modes.

Deploys to Vercel. Add environment variables from .env.example (except INNGEST_DEV).

1. Push to GitHub and merge to main (CI must pass)
2. Import repo in Vercel
3. Add Production environment variables
4. Run npx prisma migrate deploy against production DB
5. Redeploy

Supabase pgbouncer handles pooling — DATABASE_URL uses ?pgbouncer=true; DIRECT_URL for migrations only.

npm run dev          # Development server
npm run build        # prisma generate + production build
npm run type-check   # tsc --noEmit
npm run lint         # ESLint
npm run format       # Prettier
npm test             # Vitest
npm run test:e2e     # Playwright
npx tsx scripts/benchmark-sample.ts --estimate-only   # Case study metrics (offline)

1. Problem — Unstructured review text doesn't scale; manual theming breaks past dozens of rows.
2. Approach — Embeddings + k-means + LLM summarization with atomic job claiming and share-gated read-only reports.
3. Tradeoff — Chose share-link collaboration over team workspaces and email invites (no custom domain on Vercel free tier; removed half-built org schema in RL-013).
4. Reliability — Inngest + waitUntil fallback, Upstash rate limits, /api/health, 93 unit tests, Playwright e2e, GitHub Actions CI.
5. Outcome — CSV → themed report in < 60s, ~$0.0004 per 12-review sample run, PDF/CSV export, password-protected links for stakeholders.

MIT

Built by Abdu Alim Arlikhozhaev · Live demo · Issues