ReviewLens — Review and Returns Analysis for Stores

Overview#

ReviewLens helps small e-commerce brands understand why customers are unhappy. A store owner rarely has time to read hundreds of reviews and return notes, so patterns such as "this boot runs small" or "this sandal arrives late" stay hidden. ReviewLens collects that feedback, groups it into themes, ranks the products that cause the most trouble and writes a short, practical report.

It has three faces: a free mini-audit built from a store's public reviews, a paid full audit that adds returns and competitor data, and a monthly monitor that sends weekly reports and alerts for one connected store. "ReviewLens" is a working name.

My role#

I did the full build: the product plan, the Python back end and workers, the AI layer and prompt library, report generation, the Next.js client and admin apps, billing, the Shopify and WordPress integrations, security and deployment.

The problem#

Reviews and returns are the most honest data a store has, but they arrive as unstructured text spread over review apps, store platforms and spreadsheets. Generic AI summaries do not solve it: they sound confident, invent figures and give advice nobody can act on. A store owner needs numbers they can trust and a short list of fixes.

Approach & architecture#

The core rule is that all numbers are calculated by Python code, never by the language model. The model only classifies individual reviews and return reasons into themes and writes explanations from figures it is given. A separate critic step and automatic checks then compare every number in the draft report with the computed statistics, and a report that fails goes back for review instead of out to a customer.

1. Public store pages / Shopify / WordPress plugin / CSV / ingest APIthen
2. →FastAPI back end

1. Back endthen
2. →PostgreSQL (Supabase)then
3. →background workers

1. Workersthen
2. →AI classificationthen
3. →Python statisticsthen
4. →AI report writingthen
5. →number checks + critic

1. Checked reportthen
2. →admin review queuethen
3. →client dashboard, private link, PDF and email

Data can come in several ways. For prospects, a scraper reads public reviews from common review widgets. Connected stores use a Shopify app or a WordPress plugin I built for WooCommerce, and any other platform can use a documented ingest API or a CSV upload.

The Next.js front end has a client area for reports, sites, competitors, billing and team, and an admin area for leads, audits, the review queue, clients, billing and prompts. Every prompt is a versioned file, and every AI call goes through one client that records its cost.

Key challenges#

Stopping AI from making up numbers. Separating calculation from writing, then checking the writing against the calculation, was the most important design choice. A deliberately wrong number in a test report must be caught.

One subscription, one store. Each plan is bound to a single website. Keys issued for one store are rejected when used from another, the WordPress plugin proves ownership of its site through a verification challenge, and sites are re-checked over time.

Payments the browser cannot fake. Billing state only changes after a signed payment webhook is verified. Tests cover signature checks and the main purchase, refund and subscription events.

Alerts that mean something. Weekly reports only call out a change when there is enough evidence behind it, and spike alerts compare recent days with a longer baseline so one bad review does not trigger noise.

Tech stack#

• Python, FastAPI and async PostgreSQL for the API and workers, with Supabase for the database and auth.
• Gemini for classification and writing, behind a single cost-tracked client.
• Playwright for reading public review pages.
• Next.js, React and Tailwind CSS for the client and admin apps, with charts.
• Paddle for checkout and subscriptions.
• Shopify app, WordPress plugin (WordPress) and an ingest API for store connections.
• Docker and Caddy for deployment, with pytest suites for the critical paths.

Results#

All four planned build phases are implemented in code: mini-audits, full audits with payment, sites, licensing and API keys, Shopify and WordPress connections, weekly reports and alerts, and competitor tracking. Open decisions from the build are documented. It has not launched yet; the next step is the product name and live payment setup.

Screenshots#

Screenshots will be added once they can be made with sample data.