aishwarya-0409/pricepilot

1. Repo shape

- This is a two-tier application with a Next.js frontend in frontend/ and a FastAPI Python backend in backend/.

- The backend owns product discovery, scraping, persistence, and ML prediction; the frontend owns user interaction and visualization.

2. Frontend boundary

- frontend/src/app/page.tsx is the main entry page, and frontend/src/app/product/[id]/page.tsx is the product detail/comparison view.

- frontend/src/components/LoginModal.tsx suggests a user/auth surface in the UI.

- The UI is built with Next.js App Router and likely consumes backend endpoints over HTTP.

3. Backend API layer

- backend/main.py is the FastAPI application entrypoint and the place where routers are mounted.

- backend/routers/auth.py handles authentication-related endpoints.

- backend/routers/products.py exposes product search, comparison, and product-specific data retrieval.

4. Core request flow

- A user enters a product query, product URL, or image-related input in the frontend.

- The frontend sends the request to FastAPI.

- The backend resolves the product, fetches or refreshes marketplace data, stores results, and returns a normalized response for the UI.

5. Scraping / marketplace ingestion

- backend/scraper.py is the main automation subsystem and is explicitly built around Playwright according to the README.

- It likely visits external retailers such as Amazon, Flipkart, Myntra, and Meesho to collect live pricing and product metadata.

- This is the main boundary where the system talks to external services instead of internal APIs.

6. Product normalization and matching

- The backend likely has to reconcile different retailer schemas into a shared product shape before saving or comparing.

- backend/utils.py is probably used for shared parsing, cleaning, matching, or transformation logic used by the routers and scraper.

- The README’s “direct link parsing” and “image search” describe two product-identification paths that converge into the same normalized product pipeline.

7. Database layer

- backend/database.py is the database connection/session setup.

- backend/models.py defines the persistent schema, likely including products, retailer listings, historical prices, and possibly users/auth records.

- backend/reset_db.py, backend/fix_db.py, and backend/seed.py indicate the repo includes DB lifecycle and maintenance scripts, not just runtime code.

8. Historical price tracking

- The architecture is centered on storing price history over time, not just current snapshots.

- That historical store is what enables the comparison graph and trend analysis shown in the README screenshots.

- The backend likely returns both current offers and time-series data to support the charting experience in the frontend.

9. ML prediction subsystem

- backend/ml_engine.py is a separate prediction layer from scraping and CRUD.

- Per the README, it uses a simple regression approach to estimate future price movement and produce recommendation-style output such as whether to buy now or wait.

- This subsystem consumes historical price data from the database and returns advisory scores or forecasts to the products API.

10. Auth and user experience boundary

- backend/routers/auth.py and frontend/src/components/LoginModal.tsx show the app has an explicit auth flow.

- Authentication is a distinct backend concern, separated from product/search logic, which is a useful boundary for architecture diagrams.

11. Operational / development utilities

- backend/test_actual_scraper.py suggests scraper validation against live target sites.

- The backend scripts (seed, reset_db, fix_db) imply the project is actively managing schema and data quality during development.

- The frontend has standard Next.js build tooling plus ESLint and TypeScript configuration, indicating a typed UI layer with normal web-app development workflow.

12. Primary architecture diagram takeaway

- The cleanest diagram is: Next.js UI → FastAPI API → [scraper, database, ML engine] → response back to UI.

- External e-commerce sites sit on the far side of the scraper boundary.

- The database is the shared source of truth connecting live scrape results, historical charts, and ML predictions.