# kushagra-garg-27/cartlens architecture

> Architecture diagram of the GitHub repository kushagra-garg-27/cartlens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kushagra-garg-27/cartlens
- Repository: https://github.com/kushagra-garg-27/cartlens

## Overview

#### 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`

Main entry points: [`backend/src/db/schema.ts`](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/db/schema.ts) (PostgreSQL), [`backend/src/routes/compare.routes.js`](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/routes/compare.routes.js) (Product workflow routes), [`backend/src/services/job.enqueuer.js`](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/job.enqueuer.js) (Scrape job queueing), [`backend/src/cron/watchlist.cron.js`](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/cron/watchlist.cron.js) (Lifecycle schedulers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client runtimes"]
  node_extension["Chrome extension<br/>Manifest V3 client<br/>[manifest.json]"]
  node_content["Product page capture<br/>content script<br/>[content.js]"]
  node_extension_background["Extension coordinator<br/>background script<br/>[background.js]"]
  node_web_app["React web app<br/>web client<br/>[App.tsx]"]
  node_web_api_client["Web API client<br/>[apiClient.ts]"]
end

subgraph group_api["Backend API"]
  node_backend["Express backend<br/>Node API runtime<br/>[server.ts]"]
  node_auth["JWT authentication<br/>route middleware<br/>[auth.middleware.js]"]
  node_workflow_routes["Product workflow routes<br/>Express routes<br/>[compare.routes.js]"]
end

subgraph group_pipeline["Product intelligence pipeline"]
  node_resolver["Product resolver<br/>orchestration service"]
  node_job_enqueuer["Scrape job queueing<br/>job service<br/>[job.enqueuer.js]"]
  node_scraper_runner["Scraper runner<br/>scrape dispatcher<br/>[scraper.runner.js]"]
  node_retailer_scrapers["Retailer scrapers<br/>platform adapters<br/>[index.ts]"]
  node_normalizer["Canonical matching<br/>normalization service"]
  node_price_intelligence["Price and decision intelligence<br/>aggregation services<br/>[priceAggregator.ts]"]
  node_response_assembler["Comparison response<br/>response service"]
end

subgraph group_data["Data and automation"]
  node_postgres[("PostgreSQL<br/>system of record<br/>[schema.ts]")]
  node_scheduled_jobs["Lifecycle schedulers<br/>cron jobs<br/>[watchlist.cron.js]"]
  node_alerts["Alert delivery<br/>notification service<br/>[alert.service.js]"]
end

node_extension -->|"injects"| node_content
node_content -->|"product observations"| node_extension_background
node_extension_background -->|"authenticated REST"| node_backend
node_web_app -->|"uses"| node_web_api_client
node_web_api_client -->|"authenticated REST"| node_backend
node_backend -->|"protects routes"| node_auth
node_auth -->|"authorizes"| node_workflow_routes
node_workflow_routes -->|"resolves requests"| node_resolver
node_resolver -->|"queues missing data"| node_job_enqueuer
node_job_enqueuer -->|"scrape jobs"| node_scraper_runner
node_scraper_runner -->|"dispatches"| node_retailer_scrapers
node_retailer_scrapers -->|"raw listings"| node_normalizer
node_normalizer -->|"canonical listings"| node_price_intelligence
node_price_intelligence -->|"prices, offers, rankings"| node_response_assembler
node_response_assembler -->|"comparison payload"| node_workflow_routes
node_normalizer -->|"products and listings"| node_postgres
node_price_intelligence -->|"price history and insights"| node_postgres
node_job_enqueuer -->|"job state"| node_postgres
node_workflow_routes -->|"watchlists and user data"| node_postgres
node_scheduled_jobs -->|"reads watched and stale records"| node_postgres
node_scheduled_jobs -->|"refreshes products"| node_job_enqueuer
node_scheduled_jobs -->|"triggers notifications"| node_alerts
node_alerts -->|"uses watch and price state"| node_postgres

click node_extension "https://github.com/kushagra-garg-27/cartlens/blob/main/extension/manifest.json"
click node_content "https://github.com/kushagra-garg-27/cartlens/blob/main/extension/content.js"
click node_extension_background "https://github.com/kushagra-garg-27/cartlens/blob/main/extension/background.js"
click node_web_app "https://github.com/kushagra-garg-27/cartlens/blob/main/web-app/src/App.tsx"
click node_web_api_client "https://github.com/kushagra-garg-27/cartlens/blob/main/web-app/src/services/api/apiClient.ts"
click node_backend "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/server.ts"
click node_auth "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/middleware/auth.middleware.js"
click node_workflow_routes "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/routes/compare.routes.js"
click node_resolver "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/product.resolver.js"
click node_job_enqueuer "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/job.enqueuer.js"
click node_scraper_runner "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/scrapers/scraper.runner.js"
click node_retailer_scrapers "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/scrapers/index.ts"
click node_normalizer "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/productNormalizer.ts"
click node_price_intelligence "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/priceAggregator.ts"
click node_response_assembler "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/response.assembler.js"
click node_postgres "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/db/schema.ts"
click node_scheduled_jobs "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/cron/watchlist.cron.js"
click node_alerts "https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/alert.service.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_content,node_extension_background,node_web_app,node_web_api_client toneBlue
class node_backend,node_auth,node_workflow_routes toneAmber
class node_resolver,node_job_enqueuer,node_scraper_runner,node_retailer_scrapers,node_normalizer,node_price_intelligence,node_response_assembler toneMint
class node_postgres,node_scheduled_jobs,node_alerts toneRose
```

## Components

### Client runtimes

- [Chrome extension](https://github.com/kushagra-garg-27/cartlens/blob/main/extension/manifest.json): Manifest V3 client · Captures supported retailer product pages and renders comparisons. · `extension/manifest.json`
- [Product page capture](https://github.com/kushagra-garg-27/cartlens/blob/main/extension/content.js): content script · `extension/content.js`
- [Extension coordinator](https://github.com/kushagra-garg-27/cartlens/blob/main/extension/background.js): background script · `extension/background.js`
- [React web app](https://github.com/kushagra-garg-27/cartlens/blob/main/web-app/src/App.tsx): web client · Authenticated product, search, and watchlist UI. · `web-app/src/App.tsx`
- [Web API client](https://github.com/kushagra-garg-27/cartlens/blob/main/web-app/src/services/api/apiClient.ts): API client · `web-app/src/services/api/apiClient.ts`

### Backend API

- [Express backend](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/server.ts): Node API runtime · REST API bootstrap and application host. · `backend/src/server.ts`
- [JWT authentication](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/middleware/auth.middleware.js): route middleware · `backend/src/middleware/auth.middleware.js`
- [Product workflow routes](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/routes/compare.routes.js): Express routes · Comparison, observation, and watchlist endpoints. · `backend/src/routes/compare.routes.js`

### Product intelligence pipeline

- [Product resolver](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/product.resolver.js): orchestration service · Resolves observed or requested products into scrapeable listings. · `backend/src/services/product.resolver.js`
- [Scrape job queueing](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/job.enqueuer.js): job service · `backend/src/services/job.enqueuer.js`
- [Scraper runner](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/scrapers/scraper.runner.js): scrape dispatcher · Dispatches retailer-specific scraping work. · `backend/src/scrapers/scraper.runner.js`
- [Retailer scrapers](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/scrapers/index.ts): platform adapters · Amazon, Flipkart, Croma, and other volatile retailer integrations. · `backend/src/scrapers/index.ts`
- [Canonical matching](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/productNormalizer.ts): normalization service · Normalizes titles and variants across stores. · `backend/src/services/productNormalizer.ts`
- [Price and decision intelligence](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/priceAggregator.ts): aggregation services · Aggregates prices and offers; ranks, detects deals, compares specs, and enriches recommendations. · `backend/src/services/priceAggregator.ts`
- [Comparison response](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/response.assembler.js): response service · `backend/src/services/response.assembler.js`

### Data and automation

- [PostgreSQL](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/db/schema.ts): system of record · Stores products, listings, history, jobs, watchlists, affinity, and platform health. · `backend/src/db/schema.ts`
- [Lifecycle schedulers](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/cron/watchlist.cron.js): cron jobs · Refreshes watches, detects stale data, cleans records, and prepares sale alerts. · `backend/src/cron/watchlist.cron.js`
- [Alert delivery](https://github.com/kushagra-garg-27/cartlens/blob/main/backend/src/services/alert.service.js): notification service · Delivers watchlist and sale alerts through email integration. · `backend/src/services/alert.service.js`

## Connections

- Chrome extension → Product page capture: injects
- Product page capture → Extension coordinator: product observations
- Extension coordinator → Express backend: authenticated REST
- React web app → Web API client: uses
- Web API client → Express backend: authenticated REST
- Express backend → JWT authentication: protects routes
- JWT authentication → Product workflow routes: authorizes
- Product workflow routes → Product resolver: resolves requests
- Product resolver → Scrape job queueing: queues missing data
- Scrape job queueing → Scraper runner: scrape jobs
- Scraper runner → Retailer scrapers: dispatches
- Retailer scrapers → Canonical matching: raw listings
- Canonical matching → Price and decision intelligence: canonical listings
- Price and decision intelligence → Comparison response: prices, offers, rankings
- Comparison response → Product workflow routes: comparison payload
- Canonical matching → PostgreSQL: products and listings
- Price and decision intelligence → PostgreSQL: price history and insights
- Scrape job queueing → PostgreSQL: job state
- Product workflow routes → PostgreSQL: watchlists and user data
- Lifecycle schedulers → PostgreSQL: reads watched and stale records
- Lifecycle schedulers → Scrape job queueing: refreshes products
- Lifecycle schedulers → Alert delivery: triggers notifications
- Alert delivery → PostgreSQL: uses watch and price state