# aishwarya-0409/pricepilot architecture

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

- Interactive diagram: https://gitdiagram.com/aishwarya-0409/pricepilot
- Repository: https://github.com/aishwarya-0409/pricepilot

## Overview

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.

Main entry points: [`backend/routers/products.py`](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/routers/products.py) (Products API), [`backend/database.py`](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/database.py) (Database), [`backend/scraper.py`](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/scraper.py) (Scraper), [`backend/utils.py`](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/utils.py) (Normalize)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_home["Search UI<br/>Next.js page<br/>[page.tsx]"]
  node_ui_detail["Product View<br/>Next.js page<br/>[page.tsx]"]
  node_ui_auth["Login Modal<br/>UI component<br/>[LoginModal.tsx]"]
end

subgraph group_backend["Backend"]
  node_api_main["API App<br/>FastAPI entrypoint<br/>[main.py]"]
  node_api_auth["Auth API<br/>router<br/>[auth.py]"]
  node_api_products["Products API<br/>router<br/>[products.py]"]
  node_scraper["Scraper<br/>Playwright service<br/>[scraper.py]"]
  node_normalize["Normalize<br/>utils<br/>[utils.py]"]
  node_db[("Database<br/>session layer<br/>[database.py]")]
  node_models["Data Models<br/>ORM schema<br/>[models.py]"]
  node_ml["Price ML<br/>prediction engine<br/>[ml_engine.py]"]
  node_seed["Seed Data<br/>db script<br/>[seed.py]"]
  node_reset["Reset DB<br/>db script<br/>[reset_db.py]"]
  node_fixdb["Fix DB<br/>maintenance script<br/>[fix_db.py]"]
  node_scraper_test["Scraper Test<br/>validation script"]
end

subgraph group_external["External"]
  node_retailers{{"Retail Sites<br/>external marketplaces"}}
end

node_ui_home -->|"search / compare"| node_api_products
node_ui_detail -->|"load product"| node_api_products
node_ui_auth -->|"login"| node_api_auth
node_api_main -->|"mounts"| node_api_auth
node_api_main -->|"mounts"| node_api_products
node_api_products -->|"refresh data"| node_scraper
node_api_products -->|"read / write"| node_db
node_api_products -->|"forecast"| node_ml
node_scraper -->|"crawl"| node_retailers
node_scraper -->|"parse"| node_normalize
node_api_products -->|"match"| node_normalize
node_normalize -->|"shape data"| node_models
node_db -->|"stores"| node_models
node_ml -->|"history"| node_db
node_seed -->|"populate"| node_db
node_reset -->|"rebuild"| node_db
node_fixdb -->|"repair"| node_db
node_scraper_test -->|"validate"| node_scraper

click node_ui_home "https://github.com/aishwarya-0409/pricepilot/blob/main/frontend/src/app/page.tsx"
click node_ui_detail "https://github.com/aishwarya-0409/pricepilot/blob/main/frontend/src/app/product/[id]/page.tsx"
click node_ui_auth "https://github.com/aishwarya-0409/pricepilot/blob/main/frontend/src/components/LoginModal.tsx"
click node_api_main "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/main.py"
click node_api_auth "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/routers/auth.py"
click node_api_products "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/routers/products.py"
click node_scraper "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/scraper.py"
click node_normalize "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/utils.py"
click node_db "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/database.py"
click node_models "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/models.py"
click node_ml "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/ml_engine.py"
click node_seed "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/seed.py"
click node_reset "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/reset_db.py"
click node_fixdb "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/fix_db.py"
click node_scraper_test "https://github.com/aishwarya-0409/pricepilot/blob/main/backend/test_actual_scraper.py"

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_ui_home,node_ui_detail,node_ui_auth toneBlue
class node_api_main,node_api_auth,node_api_products,node_scraper,node_normalize,node_db,node_models,node_ml,node_seed,node_reset,node_fixdb,node_scraper_test toneAmber
class node_retailers toneMint
```

## Components

### Frontend

Next.js UI and client-side interaction layer

- [Search UI](https://github.com/aishwarya-0409/pricepilot/blob/main/frontend/src/app/page.tsx): Next.js page · Main entry page for product queries and browsing · `frontend/src/app/page.tsx`
- [Product View](https://github.com/aishwarya-0409/pricepilot/blob/main/frontend/src/app/product/[id]/page.tsx): Next.js page · Product detail, comparison, and trend view · `frontend/src/app/product/[id]/page.tsx`
- [Login Modal](https://github.com/aishwarya-0409/pricepilot/blob/main/frontend/src/components/LoginModal.tsx): UI component · Authentication entry surface in the frontend · `frontend/src/components/LoginModal.tsx`

### Backend

FastAPI API, scraping, storage, and prediction layer

- [API App](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/main.py): FastAPI entrypoint · Application setup and router mounting · `backend/main.py`
- [Auth API](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/routers/auth.py): router · Authentication endpoints · `backend/routers/auth.py`
- [Products API](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/routers/products.py): router · Search, compare, and product retrieval endpoints · `backend/routers/products.py`
- [Scraper](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/scraper.py): Playwright service · Marketplace automation and live data collection · `backend/scraper.py`
- [Normalize](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/utils.py): utils · Parsing, cleaning, and product matching helpers · `backend/utils.py`
- [Database](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/database.py): session layer · Database connection and session setup · `backend/database.py`
- [Data Models](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/models.py): ORM schema · Persistent entities for products, listings, history, and users · `backend/models.py`
- [Price ML](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/ml_engine.py): prediction engine · Regression-based price forecasting and buy-or-wait guidance · `backend/ml_engine.py`
- [Seed Data](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/seed.py): db script · Initial data loading for development · `backend/seed.py`
- [Reset DB](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/reset_db.py): db script · Database reset and rebuild utility · `backend/reset_db.py`
- [Fix DB](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/fix_db.py): maintenance script · Schema or data repair utility · `backend/fix_db.py`
- [Scraper Test](https://github.com/aishwarya-0409/pricepilot/blob/main/backend/test_actual_scraper.py): validation script · Live scraper verification against target sites · `backend/test_actual_scraper.py`

### External

Third-party retailers and services

- **Retail Sites**: external marketplaces · Amazon, Flipkart, Myntra, Meesho, and similar sources

## Connections

- Search UI → Products API: search / compare · Frontend sends product queries to the API
- Product View → Products API: load product · Detail view requests normalized product and trend data
- Login Modal → Auth API: login · Authentication flow from UI to backend
- API App → Auth API: mounts · Application registers auth routes
- API App → Products API: mounts · Application registers product routes
- Products API → Scraper: refresh data · Product requests can trigger live scraping and ingestion
- Products API → Database: read / write · API reads cached data and persists results
- Products API → Price ML: forecast · Product API asks for price prediction and advice
- Scraper → Retail Sites: crawl · Scraper interacts with external marketplace pages
- Scraper → Normalize: parse · Raw marketplace data is cleaned and reconciled
- Products API → Normalize: match · Direct links and search inputs are normalized into product records
- Normalize → Data Models: shape data · Normalized product structures map to persisted entities
- Database → Data Models: stores · Models define the schema used by the database layer
- Price ML → Database: history · Forecasting consumes historical price data
- Seed Data → Database: populate · Seed script initializes data
- Reset DB → Database: rebuild · Reset utility recreates database state
- Fix DB → Database: repair · Maintenance script corrects database issues
- Scraper Test → Scraper: validate · Validation script exercises live scraping behavior