System Requirements Document for price-pilot-ai

1. Introduction

PriceWise AI (delivered under the project name price-pilot-ai) is a subscription-based shopping intelligence platform for Indian online shoppers. It answers one question with evidence rather than guesswork: should I buy this product now, or wait?

The product tracks product prices across Amazon, Flipkart, Myntra, Meesho and Ajio, stores daily price history, sends price-drop alerts when a user's threshold is crossed, and produces an AI Buy Now vs Wait recommendation grounded in historical price, sale patterns and seasonal discounts. It also provides smart notifications, a categorized wishlist with priorities and budget tracking, and a cross-marketplace comparison showing the cheapest option, delivery estimate and savings amount.

The audience is four accepted roles: Free User, Premium User, Pro User and Admin. Shoppers use the platform to avoid overpaying; the Admin operates the platform's users, subscriptions, tracked products, crawlers, analytics and notifications.

The current delivery is a first-party web application with application-owned identity, background crawler and alert automation, and outbound push/email notification delivery. Phase 2 and Phase 3 items (AI assistant, Telegram bot, WhatsApp alerts, Chrome extension, mobile app, price-prediction AI, affiliate earnings, cashback comparison, international marketplaces, ML-based price forecasting) are explicitly future and are not part of current scope.

2. System Overview

PriceWise AI is delivered as a Next.js / React / Tailwind CSS web application backed by a NestJS API, PostgreSQL storage, Redis cache and BullMQ background jobs. A crawler service scrapes product data, prices and stock status from Amazon, Flipkart, Myntra, Meesho and Ajio on a 4–6 hour schedule. Background jobs perform daily price updates, price monitoring and alert processing. The AI module produces Buy Now vs Wait predictions, similar-product recommendations and smart notifications.

Actors

• Free User — ₹0/month shopper; tracks up to 5 products, sees basic price history, receives limited alerts.
• Premium User — ₹99/month subscriber; unlimited tracking, AI recommendations, advanced alerts, price prediction, wishlist management.
• Pro User — ₹199/month subscriber; same shopping-intelligence workflow at the Pro tier.
• Admin — platform operator; manages users, subscriptions, tracked products, crawlers, analytics and notifications.

Current behavior owned by the product

Anonymous product explanation and entry; self-service shopper enrollment and returning verification; a distinct Admin returning-verification entry; a post-login dashboard; product search across five marketplaces; product tracking with plan-limit enforcement; price history over 7/30/90/365-day ranges with Highest, Lowest, Average and Current Price metrics; per-product threshold alerts delivered by push and email; smart notifications; cross-marketplace comparison; AI Buy Now vs Wait recommendation for entitled plans; wishlist with categories, priorities and budget tracking; subscription plan viewing and management across Free, Premium, Pro and Enterprise (custom pricing); and an Admin Panel for platform operations.

Narrow exclusions (current scope)

• No AI assistant, Telegram bot, WhatsApp alerts, Chrome extension or mobile app (Phase 2).
• No price-prediction AI, affiliate earnings, cashback comparison or international marketplaces (Phase 3).
• No ML-based price forecasting.
• No blue/indigo accent palette, no rounded corners, no soft shadows, no glass/frosted panels, no gradients, no second typeface alongside Archivo, no decorative illustration or 3D renders.

2a. Product Interpretation and Delivery Boundary

PriceWise AI is a first-party web product with application-owned identity. Shoppers establish their own account on first use and verify themselves on return so that their tracked products, thresholds, wishlist, alerts and plan remain bound to them. The Admin is a privileged operator role and verifies through a distinct role-appropriate entry, because the shopper entry cannot establish Admin access.

The Landing page is anonymously reachable and explains the product before any identity is established. Login is anonymously reachable and carries both first-use enrollment and returning verification for shoppers. Admin Login is anonymously reachable and carries returning verification for the Admin. All other destinations require an established identity, and the AI Recommendation and Wishlist destinations additionally require Premium or Pro entitlement.

Background automation (crawler scheduling, price monitoring, alert evaluation and dispatch) runs without a human in the loop, but every human-facing outcome it produces — a notification, a recommendation, a comparison, a price history view — is owned by a first-party page where the affected persona sees and acts on it.

Future horizons are explicitly separated: Phase 2 and Phase 3 capabilities are documented in Section 11 and are excluded from current pages, requirements and acceptance.

2b. Source Content Inventory

Not applicable — no reference directive with content_source authority was supplied.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression of the subscription shopping-intelligence product; the buy-now-or-wait promise; the five supported marketplaces (Amazon, Flipkart, Myntra, Meesho, Ajio); the plan ladder (Free ₹0/month, Premium ₹99/month, Pro ₹199/month, Enterprise custom pricing).
• Primary actions: Enter a product query into the hero search field; proceed to Login to enroll or verify.
• Supporting actions: Read the plan ladder; read the marketplace band.
• Domain entities: Product query, marketplace, plan.
• Component responsibilities: Hero headline block (Archivo Black, flush-left, 72–96px clamp); hero search input (full-width, black-ruled, 0px radius); live price-history chart panel (black 1.5px line, red current-price dot, dashed red threshold rule, flat 12% black area fill); four metric rows (HIGHEST / LOWEST / AVERAGE / CURRENT) with uppercase 13px labels and right-aligned tabular prices; hero verdict stamp (180px circle overlapping the chart panel edge — black fill "BUY NOW" or red outline "WAIT", with the expected-drop window in 13px caps beneath); full-bleed black marketplace band with five white-caps names separated by thin rules.
• States: Loading — chart panel shows the ruled frame and metric rows with placeholder tabular figures. Empty — no query entered; hero search field is focused-ready and the chart panel shows the schematic frame. Success — query submitted, routed to Login for identity establishment. Error — query submission fails; inline black-ruled message under the input, input retains the query. Recovery — user edits the query and resubmits.

Login

• Information/state: Anonymous identity-access surface for shoppers; carries both first-use enrollment and returning verification.
• Primary actions: Enroll a new shopper account; verify a returning shopper.
• Supporting actions: Switch between enrollment and returning verification; proceed to Admin Login if the visitor is an operator.
• Domain entities: Shopper identity, session.
• Component responsibilities: Mode switch (ENROLL / VERIFY) as hard-edged black-outlined tabs with the active one filled black; enrollment fields; verification fields; submit rectangle that fills black on hover; inline error region.
• States: Loading — submit control disabled with a ruled progress indicator. Empty — enrollment mode with blank fields. Success — identity established, routed to Dashboard. Error — invalid or duplicate enrollment, or failed verification; inline black-ruled error message, entered values retained. Recovery — user corrects the field and resubmits, or switches mode.

Dashboard

• Information/state: Post-login hub summarizing tracked products, active alerts and available recommendations; routes to page-sized work.
• Primary actions: Open Product Search; open Product Tracking; open Price History; open Alerts; open Notifications; open Product Comparison; open AI Recommendation; open Wishlist; open Subscription.
• Supporting actions: Read the tracked-product summary; read the alert summary; read the recommendation summary.
• Domain entities: Tracked product, alert, recommendation, plan entitlement.
• Component responsibilities: Numbered nav rail (fixed left column, 01–05 uppercase labels: Search, Track, History, Alerts, Wishlist; active item's number in red with a 1px rule extending to the content edge); labelled panels with uppercase headers and hairline black dividers; tracked-product summary panel; alert summary panel; recommendation summary panel; plan-entitlement indicator.
• States: Loading — panels render ruled frames with placeholder tabular figures. Empty — no tracked products yet; panel shows a ruled empty state with a direct route to Product Search. Success — panels populated with tracked products, alerts and recommendations. Error — a panel fails to load; that panel shows an inline black-ruled error with a retry control while other panels remain usable. Recovery — retry the failed panel.

Product Search

• Information/state: Search across Amazon, Flipkart, Myntra, Meesho and Ajio with results displayed to the user.
• Primary actions: Enter a query (e.g. iPhone 17, Samsung TV, Nike Shoes); submit the search; open a result.
• Supporting actions: Track a result directly; open a result's price history; open a result's comparison.
• Domain entities: Product query, product result, marketplace, price, stock status.
• Component responsibilities: Search input (black-ruled, 0px radius); result table with marketplace name, price, delivery estimate and savings aligned on a shared baseline grid; small hard-edged product thumbnail squares inside table rows; per-row Track control; per-row History and Compare controls.
• States: Loading — result table renders ruled rows with placeholder tabular figures. Empty — no query yet, or no results for the query; ruled empty state with the query retained. Success — results displayed across the five marketplaces. Error — search fails or a marketplace source is unavailable; inline black-ruled error naming the affected source, with partial results shown where available. Recovery — retry the search or narrow the query.

Product Tracking

• Information/state: The tracked-product list; each Track action adds the product to the watchlist and starts price monitoring; plan limits are enforced here.
• Primary actions: Track a product; untrack a product; open a tracked product's price history; open its alerts; open its comparison.
• Supporting actions: Read the current tracked count against the plan limit; read monitoring status per product.
• Domain entities: Tracked product, watchlist entry, monitoring status, plan entitlement.
• Component responsibilities: Tracked-product table with uppercase column headers and hairline black dividers; per-row monitoring-status indicator; per-row untrack control; plan-limit banner; route controls to Price History, Alerts and Product Comparison.
• States: Loading — table renders ruled rows with placeholder values. Empty — no tracked products; ruled empty state with a direct route to Product Search. Success — product added to the watchlist and price monitoring started; row appears with monitoring active. Error — Free User at the 5-product limit attempts to track a sixth product; the attempt is blocked with an inline black-ruled message stating the limit and offering the Subscription route. Recovery — untrack a product to free a slot, or move to a paid plan via Subscription.

Price History

• Information/state: Daily stored prices displayed over 7-day, 30-day, 90-day and 1-year ranges, with Highest Price, Lowest Price, Average Price and Current Price metrics.
• Primary actions: Switch the history range (7 / 30 / 90 / 365); read the metrics; read the chart.
• Supporting actions: Open the product's alerts; open the product's comparison; open the product's AI recommendation where entitled.
• Domain entities: Price history point, price metric, product, marketplace.
• Component responsibilities: Price-history chart as the largest object on the page (black 1.5px line, red current-price dot, dashed red horizontal threshold rule, flat 12% black area fill); four hard-edged black-outlined range tabs with the active one filled black; metric rows with uppercase 13px labels and right-aligned tabular prices; product header with marketplace attribution.
• States: Loading — chart frame and metric rows render with placeholder tabular figures. Empty — insufficient stored history for the selected range; ruled empty state naming the range and the earliest available data. Success — chart and all four metrics displayed for the selected range. Error — history fails to load; inline black-ruled error with a retry control. Recovery — retry, or switch to a shorter range that has data.

Alerts

• Information/state: Per-product threshold price-drop alert setup; when the price falls below the threshold, a push notification and an email notification are sent.
• Primary actions: Set a threshold price for a tracked product; save the alert; edit the threshold; remove the alert.
• Supporting actions: Read the current price against the threshold; read the delivery channels (push, email) for the alert.
• Domain entities: Alert, threshold price, current price, delivery channel, tracked product.
• Component responsibilities: Threshold input (black-ruled, 0px radius, tabular figures); current-price reference row; channel indicators for push and email; alert list with uppercase headers and hairline black dividers; per-alert edit and remove controls.
• States: Loading — alert list renders ruled rows with placeholder values. Empty — no alerts configured; ruled empty state with a direct route to Product Tracking. Success — threshold saved; alert listed as active with its channels. Error — threshold is invalid (non-numeric, zero, or not below the current price); inline black-ruled message, entered value retained. Recovery — correct the threshold and resave.

Notifications

• Information/state: Smart notifications for price dropped, new lowest price, product back in stock, and better alternative available.
• Primary actions: Read notifications; open the referenced product; mark notifications as read.
• Supporting actions: Filter by notification type; read the delivery record for push and email.
• Domain entities: Notification, notification type, referenced product, delivery channel.
• Component responsibilities: Notification list with type labels in uppercase 13px caps; per-notification product reference; per-notification read control; type filter as hard-edged black-outlined tabs with the active one filled black.
• States: Loading — list renders ruled rows with placeholder values. Empty — no notifications yet; ruled empty state with a direct route to Product Tracking. Success — notifications listed with type, product and time. Error — notifications fail to load; inline black-ruled error with a retry control. Recovery — retry the load.

Product Comparison

• Information/state: Side-by-side Amazon, Flipkart, Myntra and Meesho prices showing the cheapest option, delivery estimate and savings amount.
• Primary actions: Read the comparison table; open the cheapest option's product page; open the product's price history.
• Supporting actions: Read the savings column; read delivery estimates per marketplace.
• Domain entities: Marketplace price, cheapest option, delivery estimate, savings amount, product.
• Component responsibilities: Comparison table with marketplace rows aligned on a shared baseline; cheapest row marked with a solid red left edge bar; savings amount set in mustard #E3B23C tabular figures; delivery-estimate column; small hard-edged product thumbnail squares inside rows.
• States: Loading — table renders ruled rows with placeholder tabular figures. Empty — the product is not listed on any compared marketplace; ruled empty state. Success — all available marketplace rows displayed with the cheapest marked and savings computed. Error — one or more marketplace sources unavailable; affected rows show an inline black-ruled unavailable state while remaining rows display normally. Recovery — retry the affected source.

AI Recommendation

• Information/state: A BUY NOW or WAIT verdict with reasoning derived from historical price, sale patterns and seasonal discounts; Premium and Pro entitlement.
• Primary actions: Request the recommendation for a product; read the verdict and its explanation.
• Supporting actions: Open the product's price history; open the product's comparison; open the product's alerts.
• Domain entities: Recommendation, verdict (BUY NOW / WAIT), reasoning, expected-drop window, product.
• Component responsibilities: Verdict stamp (180px circle — black fill "BUY NOW" or red outline "WAIT", with the expected-drop window in 13px caps beneath); reasoning block; supporting metric rows (current price, lowest price) with tabular figures; entitlement gate for non-entitled plans.
• States: Loading — verdict stamp area renders the ruled frame with placeholder metric rows. Empty — no recommendation available yet for the product; ruled empty state explaining that history is still accumulating. Success — verdict and reasoning displayed, e.g. current price ₹49,999 against lowest price ₹43,999 with "Wait 2-3 weeks. Expected drop during upcoming sale." Error — recommendation fails to generate; inline black-ruled error with a retry control. Recovery — retry, or open Price History to read the underlying evidence. Entitlement — a Free User reaching this page sees the entitlement gate with a route to Subscription.

Wishlist

• Information/state: Saved products with categories, priority products and budget tracking; Premium and Pro entitlement.
• Primary actions: Save a product to the wishlist; assign a category; set a priority; set and read budget tracking.
• Supporting actions: Remove a saved product; open a saved product's price history; open its comparison.
• Domain entities: Wishlist item, category, priority, budget, product.
• Component responsibilities: Wishlist table with uppercase headers and hairline black dividers; category control; priority control; budget panel with tabular figures; per-item remove control.
• States: Loading — table renders ruled rows with placeholder values. Empty — no saved products; ruled empty state with a direct route to Product Search. Success — product saved with category, priority and budget reflected. Error — save fails, or budget input is invalid; inline black-ruled message, entered values retained. Recovery — correct the input and resave. Entitlement — a Free User reaching this page sees the entitlement gate with a route to Subscription.

Subscription

• Information/state: The plan ladder — Free ₹0/month, Premium ₹99/month, Pro ₹199/month, Enterprise custom pricing — and the current plan.
• Primary actions: View plans; select a plan; manage the current plan.
• Supporting actions: Read the feature differences between plans (Free: 5 products, basic price history, limited alerts; Premium and Pro: unlimited tracking, AI recommendations, advanced alerts, price prediction, wishlist management; Enterprise: custom pricing).
• Domain entities: Plan, price, entitlement, subscription.
• Component responsibilities: Plan table with uppercase headers and hairline black dividers; per-plan feature rows; current-plan indicator; plan-selection control; Enterprise contact route.
• States: Loading — plan table renders ruled rows with placeholder values. Empty — not applicable; the plan ladder is always populated. Success — plan selected or managed; current-plan indicator updates and entitlements take effect. Error — plan change fails; inline black-ruled error with the current plan unchanged. Recovery — retry the plan change.

Admin Panel

• Information/state: Operator surface for managing users, managing subscriptions, viewing tracked products, monitoring crawlers, viewing analytics and managing notifications.
• Primary actions: Manage users; manage subscriptions; view tracked products; monitor crawlers; view analytics; manage notifications.
• Supporting actions: Read crawler health and last-run status; read analytics figures.
• Domain entities: User, subscription, tracked product, crawler, analytics metric, notification.
• Component responsibilities: Numbered nav rail carried through from the shopper surface (01–05 uppercase labels) adapted to operator sections; labelled panels with uppercase headers and hairline black dividers; user-management table; subscription-management table; tracked-products table; crawler-status panel with schematic crawler-status diagrams; analytics panel; notification-management table.
• States: Loading — panels render ruled frames with placeholder values. Empty — a section with no records shows a ruled empty state. Success — sections populated with live operational data. Error — a section fails to load; that section shows an inline black-ruled error with a retry control while other sections remain usable. Recovery — retry the failed section.

Admin Login

• Information/state: Anonymous role-appropriate returning-verification entry for the Admin; the shopper Login surface cannot establish Admin access.
• Primary actions: Verify Admin identity.
• Supporting actions: Return to the shopper Login surface.
• Domain entities: Admin identity, session.
• Component responsibilities: Verification fields; submit rectangle that fills black on hover; inline error region; route back to shopper Login.
• States: Loading — submit control disabled with a ruled progress indicator. Empty — blank verification fields. Success — Admin identity established, routed to Admin Panel. Error — failed verification; inline black-ruled error, entered values retained. Recovery — correct the field and resubmit.

3. Functional Requirements

FR-01 — Anonymous product explanation and entry (explicit) As a Free User, Premium User or Pro User, I should see an anonymous Landing page that explains the subscription shopping-intelligence product, its buy-now-or-wait promise and the five supported marketplaces, so that I understand the product before establishing identity.

• Trigger/input: anonymous visit to Landing.
• Observable result: hero headline, hero search field, live price-history chart panel with four metric rows, verdict stamp, and the full-bleed marketplace band for Amazon, Flipkart, Myntra, Meesho and Ajio.
• Access state: anonymous.
• Failure/recovery: if query submission fails, an inline black-ruled message appears under the input and the query is retained for resubmission.
• Continuation: the visitor proceeds to Login to enroll or verify.

FR-02 — Self-service shopper enrollment (required_inference) As a Free User, Premium User or Pro User, I should be able to establish my own account on first use, so that my tracked products, thresholds, wishlist, alerts and plan can be owned by me.

• Trigger/input: first-use enrollment on Login.
• Observable result: identity established and routed to Dashboard.
• Access state: anonymous entry on Login.
• Failure/recovery: invalid or duplicate enrollment shows an inline black-ruled error with entered values retained; the user corrects the field and resubmits.
• Continuation: Dashboard.

FR-03 — Returning shopper verification (required_inference) As a Free User, Premium User or Pro User, I should be able to verify myself on return, so that I resume my tracked products, alerts and plan.

• Trigger/input: returning verification on Login.
• Observable result: identity established and routed to Dashboard with prior state restored.
• Access state: anonymous entry on Login.
• Failure/recovery: failed verification shows an inline black-ruled error with entered values retained; the user corrects the field and resubmits.
• Continuation: Dashboard.

FR-04 — Admin returning verification (required_inference) As an Admin, I should verify through a distinct role-appropriate entry, so that privileged operator access is established separately from shopper access.

• Trigger/input: verification on Admin Login.
• Observable result: Admin identity established and routed to Admin Panel.
• Access state: anonymous entry on Admin Login.
• Failure/recovery: failed verification shows an inline black-ruled error with entered values retained; the user corrects the field and resubmits.
• Continuation: Admin Panel.

FR-05 — Post-login hub (explicit) As a Free User, Premium User or Pro User, I should land on a Dashboard after verification that summarizes my tracked products, alerts and recommendations and routes me to page-sized work.

• Trigger/input: arrival at Dashboard after identity establishment.
• Observable result: tracked-product, alert and recommendation panels populated, with routes to Product Search, Product Tracking, Price History, Alerts, Notifications, Product Comparison, AI Recommendation, Wishlist and Subscription.
• Access state: identity required.
• Failure/recovery: a panel that fails to load shows an inline black-ruled error with a retry control while other panels remain usable.
• Continuation: the user opens any routed destination.

FR-06 — Product search across marketplaces (explicit) As a Free User, Premium User or Pro User, I should search a product and see results from multiple ecommerce websites, so that I can find the product I want to evaluate.

• Trigger/input: a query such as iPhone 17, Samsung TV or Nike Shoes entered on Product Search.
• Observable result: results displayed from Amazon, Flipkart, Myntra, Meesho and Ajio.
• Access state: identity required.
• Failure/recovery: if search fails or a marketplace source is unavailable, an inline black-ruled error names the affected source and partial results are shown where available; the user retries or narrows the query.
• Continuation: the user opens a result, tracks it, opens its price history, or opens its comparison.

FR-07 — Product tracking (explicit) As a Free User, Premium User or Pro User, I should click Track on a product so that it is added to my watchlist and price monitoring starts.

• Trigger/input: Track action on a product from Product Search or Product Tracking.
• Observable result: the product appears in the watchlist with monitoring active.
• Access state: identity required.
• Failure/recovery: a Free User at the 5-product limit is blocked with an inline black-ruled message stating the limit and offering the Subscription route; the user untracks a product to free a slot or moves to a paid plan.
• Continuation: the tracked product is available for Price History, Alerts and Product Comparison.

FR-08 — Free plan tracking limit (explicit) As a Free User, I should be limited to tracking 5 products, so that the Free plan boundary is enforced.

• Trigger/input: attempt to track a sixth product.
• Observable result: the attempt is blocked and the limit is stated.
• Access state: identity required; Free plan.
• Failure/recovery: untrack a product to free a slot, or move to a paid plan via Subscription.
• Continuation: tracking resumes within the limit or under a paid plan.

FR-09 — Daily price history storage and range views (explicit) As a Free User, Premium User or Pro User, I should view stored daily prices over 7-day, 30-day, 90-day and 1-year ranges, so that I can judge whether the current price is high or low.

• Trigger/input: selecting a range on Price History.
• Observable result: the chart redraws for the selected range.
• Access state: identity required; Free Users receive basic price history.
• Failure/recovery: insufficient history for a range shows a ruled empty state naming the range and the earliest available data; a load failure shows an inline black-ruled error with retry.
• Continuation: the user