kushagra-garg-27/cartlens

Purpose and entry points

SmartCompare Pro compares Indian e-commerce prices, records price history, and supports watchlists, alerts, ranking, and AI recommendations. Its primary consumer is a Manifest V3 Chrome extension; a separate React web app exposes similar product/deal workflows.

• Extension runtime: extension/manifest.json, extension/content.js, extension/background.js

• Backend API/bootstrap: backend/src/index.js, backend/src/server.ts

• Web app bootstrap: web-app/src/main.tsx, web-app/src/App.tsx

Client capture and API boundary

The extension injects into supported product pages, extracts product details locally, and communicates with the backend REST API using JWT authentication. The background script coordinates extension-side work, while popup/panel UI renders comparison results.

• extension/content.js

• extension/background.js

• backend/src/routes/auth.routes.js, backend/src/middleware/auth.middleware.js

The React application is a separate API client with authenticated routes and product/search/watchlist views.

• web-app/src/services/api/apiClient.ts

• web-app/src/contexts/AuthContext.tsx

• web-app/src/pages/Product.tsx

API orchestration and product workflows

Express routes organize externally visible workflows: product observation/search, cross-store comparison, price history, deals, notifications, chat, and user watchlists. Route handlers delegate to services rather than directly implementing scraping or persistence.

• backend/src/routes/compare.routes.js

• backend/src/routes/observe.routes.js

• backend/src/routes/watchlist.routes.js

Important control flow: observed or requested product input is resolved/normalized, listings are fetched or queued for scraping, prices and offers are assembled into a comparison response, then persisted for history and downstream alerts.

• backend/src/services/product.resolver.js

• backend/src/services/response.assembler.js

• backend/src/services/job.enqueuer.js

Scraping and platform integration layer

Platform-specific scrapers cover the supported Indian retailers. A runner dispatches scraper work; Playwright-based infrastructure handles browser-resistant sites, with parsing/utilities separating common mechanics from retailer implementations.

• backend/src/scrapers/scraper.runner.js

• backend/src/scrapers/playwright.base.js

• backend/src/scrapers/index.ts

Representative platform implementations include backend/src/scrapers/amazon.scraper.js, backend/src/scrapers/flipkart.scraper.js, and backend/src/scrapers/croma.scraper.js. This is the principal boundary to volatile third-party retailer pages; scraper output must be normalized before becoming canonical product/listing data.

Product matching, prices, and decision intelligence

Canonicalization and matching protect against cross-store title and variant differences. Services extract price/offers, aggregate listings, compute analytics, compare specifications, and rank platforms based on user affinity. Deal detection and AI enrichment produce higher-level recommendations.

• backend/src/services/productNormalizer.ts

• backend/src/services/priceAggregator.ts

• backend/src/services/ranker.service.js

• backend/src/services/deal.detector.js

• backend/src/services/spec.comparator.js

• backend/src/services/aiIntelligence.ts

Persistence, jobs, and lifecycle automation

PostgreSQL is the system of record for products, listings, price history, scrape jobs, watchlists, platform affinity, and platform health. Schema/migrations define the durable model; database access is centralized behind DB/store modules.

• backend/src/db/schema.ts

• backend/src/db/pool.ts

• backend/migrations/001_initial_schema.sql

Scheduled jobs refresh watched products, detect stale data, clean up records, and pre-alert on sales. Alert delivery is handled through the alert service and Resend email integration.

• backend/src/cron/watchlist.cron.js

• backend/src/cron/stale.cron.js

• backend/src/services/alert.service.js

Runtime and infrastructure

The backend is Node.js/Express with Playwright/Cheerio scraping, JWT auth, PostgreSQL (documented Neon deployment), Gemini 2.5 Flash AI, and optional Resend email. Docker provisions the backend/database local stack; deployment is documented for Render.

• backend/Dockerfile

• docker-compose.yml

• backend/src/config.js