# aswajithb/ecommerce-smart-pricing-engine architecture

> Architecture diagram of the GitHub repository aswajithb/ecommerce-smart-pricing-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aswajithb/ecommerce-smart-pricing-engine
- Repository: https://github.com/aswajithb/ecommerce-smart-pricing-engine

## Overview

##### What this project is (type + purpose)
This is a **single-service Flask web application** that serves:
- A **web UI** (HTML templates + static CSS/images) for sellers to input product details and manage an inventory view.
- A **machine-learning inference pipeline** (pre-trained **Ridge Regression** + preprocessors stored as `*.joblib`) to predict an optimal price.
- A **dynamic pricing adjustment layer** (seasonality/trends/brand premiums) on top of the base ML prediction.
- A **real-time currency conversion** feature (USD → INR) using a live exchange rate source (external API call implied by README).

Deployment artifacts (`Procfile`, `DEPLOYMENT.md`, and `application.py`) strongly indicate **PaaS deployment** (e.g., AWS Elastic Beanstalk / Heroku-style process entrypoint).

##### What the file tree tells you about architecture (map files → components)
Top-level items and what they represent:

##### Web application entrypoints
- `app.py` — primary Flask app; will contain routes, request handling, model loading, inference, rendering templates.
- `application.py` — commonly used by Elastic Beanstalk as WSGI entrypoint (`application` object). Often imports from `app.py`.
- `Procfile` — defines how the web server is launched in production (e.g., `gunicorn application:application`).

##### ML model + preprocessing artifacts (runtime inference dependencies)
- `ridge_model.joblib` — trained Ridge model.
- `tv_description.joblib` — TF-IDF vectorizer for description text.
- `cv_name.joblib`, `cv_category.joblib` — likely count/vectorizers for name/category.
- `ohe_condition.joblib` — one-hot encoder for item condition.
- `lb_brand.joblib` — label binarizer/encoder for brand.

##### Data / training artifacts (not part of runtime, but relevant to architecture)
- `dataset/sample_train.tsv` — sample data; suggests training was done locally/offline.

##### Runtime/dependencies/deployment
- `requirements.txt` — Python deps (Flask, sklearn, pandas, nltk, joblib, etc.).

- **Two-stage pricing**: base **ML prediction** → **dynamic pricing adjustments**.
- **External call**: **live exchange-rate API** for USD→INR conversion.
- **Inventory dashboard**: browsing/searching listings with automated suggestions.

##### Flask Web App (Python)
- Routes/Controllers (HTTP endpoints)
- Template rendering (Jinja templates)
- Static file serving (or via platform)
##### ML Inference Pipeline (within Flask process)
- Text preprocessing (TF-IDF / vectorizers)
- Categorical encoders (OHE / label binarizer)
- Feature concatenation
- Ridge regression inference
##### Dynamic Pricing Engine (business rules)
- seasonality factor
- brand premium
- market trend factor
##### Currency Conversion Module
- calls **External Exchange Rate API**
##### Deployment/Runtime Environment
- WSGI server (Gunicorn implied by Procfile)
- Hosting platform (AWS Elastic Beanstalk per live demo URL)

##### Offline Training Pipeline
- Notebook + dataset → trains model → exports `*.joblib`
- Artifact packaging into repo/deployable slug

##### Browser → Flask: `HTTP POST /predict` (or similar) sends product fields
- name, brand, category, condition, shipping, description
##### Flask → Inference Pipeline: transforms inputs using joblib artifacts
4. **Inference Pipeline → Ridge Model**: returns `log(price)` then exponentiate (`expm1`) to USD
##### Flask → Browser: returns rendered HTML with
- predicted USD + INR
- analytics data (distributions/positioning)
##### Browser → Flask: `GET /inventory` for inventory dashboard
9. **Flask → Browser**: returns `inventory.html` + suggested prices per item (computed similarly)

If `app.py` actually persists anything (unknown from tree), update accordingly.

##### Architectural patterns / principles to highlight
- **Monolith with layered concerns**: presentation (templates), application logic (routes), domain logic (dynamic pricing), ML inference (pipeline + model artifacts).
- **Model-as-artifact**: pre-trained transformers/models loaded at startup, used at request time.
- **Separation of offline training vs online inference** (even if training code is only a notebook).

##### Technologies to label
- Flask, Jinja2 templates
- scikit-learn Ridge Regression
- TF-IDF vectorizer, OneHotEncoder/LabelBinarizer (joblib)
- joblib for persistence
- External exchange-rate API (unnamed; label generically)
- AWS Elastic Beanstalk (or “PaaS Host”) + Gunicorn/WSGI

##### Labels
- Explicit names matching repo files:
- “Flask App (`app.py` / `application.py` WSGI)”
- “Model Artifacts (`ridge_model.joblib`, `tv_description.joblib`, …)”
- “Templates (`templates/index.html`, `templates/inventory.html`)”
- “product metadata JSON/form fields”
- “feature vectors (sparse matrix)”
- “predicted price (USD), adjusted price, converted price (INR)”

##### Don’t overthink it: maximize component separation (this project benefits from it)
- Preprocessing (text vs categorical) as separate subcomponents
- Base model vs dynamic adjustment
- USD prediction vs INR conversion
- UI vs inventory dashboard routes
- Offline training vs online inference

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========= Global Actors / External =========
    Seller["Seller Browser (Web Client)"]:::client
    FX["External Exchange Rate API\n(USD→INR live rate)"]:::external

    %% ========= Deployment / Runtime Environment =========
    subgraph "PaaS Hosting Environment (e.g., AWS Elastic Beanstalk)"
        direction TB

        Proc["Process Entry (Procfile)\nStarts WSGI server"]:::infra
        WSGI["WSGI Entrypoint\n(application.py)"]:::infra
        FlaskApp["Flask Web App Runtime\n(app.py)"]:::app

        Proc -->|"launches"| WSGI
        WSGI -->|"imports/creates app"| FlaskApp
    end

    %% ========= Web UI / Presentation =========
    subgraph "Presentation Layer (Server-rendered UI)"
        direction TB

        Routes["Routes / Controllers\n(HTTP endpoints)"]:::app
        Templates["Template Rendering (Jinja2)\nindex.html + inventory.html"]:::ui
        Static["Static Assets\nCSS + Images"]:::ui
    end

    FlaskApp -->|"handles requests via"| Routes
    Routes -->|"renders"| Templates
    Routes -->|"serves"| Static

    %% ========= Pricing / Inference (In-process) =========
    subgraph "Pricing Service (In-process within Flask)"
        direction TB

        subgraph "ML Inference Pipeline (scikit-learn)"
            direction TB
            PreText["Text Preprocessing\n(TF-IDF for description)"]:::ml
            PreCat["Categorical Encoding\n(name/category/brand/condition)"]:::ml
            Feat["Feature Assembly\n(sparse vectors)"]:::ml
            Ridge["Ridge Regression Inference\n(base USD price)"]:::ml

            PreText -->|"text features"| Feat
            PreCat -->|"categorical features"| Feat
            Feat -->|"feature matrix"| Ridge
        end

        Dynamic["Dynamic Pricing Engine\n(seasonality/trends/brand premium)"]:::logic
        FXMod["Currency Converter\n(USD→INR)"]:::logic

        Ridge -->|"base price (USD)"| Dynamic
        Dynamic -->|"adjusted price (USD)"| FXMod
    end

    Routes -->|"product fields\n(name,brand,category,condition,shipping,description)"| PreText
    Routes -->|"product fields\n(name,brand,category,condition)"| PreCat
    FXMod -->|"fetch live rate"| FX
    FX -->|"USD→INR rate"| FXMod

    %% ========= Inventory View (No DB in tree) =========
    subgraph "Inventory Dashboard (UI + Suggestions)"
        direction TB
        InvRoute["Inventory Endpoint\n(GET /inventory)"]:::app
        InvLogic["Suggest Prices per Listing\n(reuses pricing pipeline)"]:::logic
        InvSource["Inventory Data Source\n(in-memory / file / sample dataset)"]:::data

        InvRoute -->|"loads inventory"| InvSource
        InvRoute -->|"computes suggestions"| InvLogic
        InvLogic -->|"calls"| PreText
        InvLogic -->|"calls"| PreCat
        InvLogic -->|"calls"| Dynamic
        InvLogic -->|"calls"| FXMod
    end

    Routes -->|"GET /inventory"| InvRoute
    InvRoute -->|"renders"| Templates

    %% ========= Client Request Flows =========
    Seller -->|"HTTP GET /"| Routes
    Routes -->|"HTML response\n(prediction form + analytics hooks)"| Seller

    Seller -->|"HTTP POST /predict\n(form fields)"| Routes
    Routes -->|"HTML response\n(predicted USD + INR + insights)"| Seller

    Seller -->|"HTTP GET /static/*"| Static

    %% ========= Model Artifacts (loaded at startup, used at runtime) =========
    subgraph "Model & Preprocessor Artifacts (joblib files)"
        direction TB
        A_Ridge[("ridge_model.joblib")]:::artifact
        A_TFIDF[("tv_description.joblib")]:::artifact
        A_Name[("cv_name.joblib")]:::artifact
        A_Category[("cv_category.joblib")]:::artifact
        A_Cond[("ohe_condition.joblib")]:::artifact
        A_Brand[("lb_brand.joblib")]:::artifact
    end

    FlaskApp -->|"loads artifacts at startup\n(file read → memory)"| A_Ridge
    FlaskApp -->|"loads artifacts at startup\n(file read → memory)"| A_TFIDF
    FlaskApp -->|"loads artifacts at startup\n(file read → memory)"| A_Name
    FlaskApp -->|"loads artifacts at startup\n(file read → memory)"| A_Category
    FlaskApp -->|"loads artifacts at startup\n(file read → memory)"| A_Cond
    FlaskApp -->|"loads artifacts at startup\n(file read → memory)"| A_Brand

    A_TFIDF -.->|"used by"| PreText
    A_Name -.->|"used by"| PreCat
    A_Category -.->|"used by"| PreCat
    A_Cond -.->|"used by"| PreCat
    A_Brand -.->|"used by"| PreCat
    A_Ridge -.->|"used by"| Ridge

    %% ========= Offline Training / Artifact Lifecycle =========
    subgraph "Offline Training (Build-time / Data Science)"
        direction TB
        DataSet[("Training Dataset\nsample_train.tsv")]:::data
        Notebook["Training & Experiment Notebook\n(Ridge + preprocessing)"]:::offline
        Export["Export joblib artifacts\n(versioned with app)"]:::offline

        DataSet -->|"load/clean/feature engineering"| Notebook
        Notebook -->|"train + evaluate"| Notebook
        Notebook -->|"serialize"| Export
        Export -.->|"produces"| A_TFIDF
        Export -.->|"produces"| A_Name
        Export -.->|"produces"| A_Category
        Export -.->|"produces"| A_Cond
        Export -.->|"produces"| A_Brand
        Export -.->|"produces"| A_Ridge
    end

    %% ========= Ops / Dependencies =========
    subgraph "Operational Context"
        direction TB
        Reqs["Python Dependencies\n(requirements.txt)"]:::ops
        DeployDoc["Deployment Guide\n(DEPLOYMENT.md)"]:::ops
    end

    Reqs -->|"installed into runtime env"| FlaskApp
    DeployDoc -.->|"informs deployment steps"| Proc

    %% ========= Click Events (from component_mapping) =========
    click FlaskApp "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/app.py"
    click WSGI "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/application.py"
    click Proc "https://github.com/aswajithb/ecommerce-smart-pricing-engine/tree/main/Procfile"

    click Templates "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/templates/index.html"
    click Templates "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/templates/inventory.html"

    click Static "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/static/css/style.css"
    click Static "https://github.com/aswajithb/ecommerce-smart-pricing-engine/tree/main/static/img/"

    click A_Ridge "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/ridge_model.joblib"
    click A_TFIDF "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/tv_description.joblib"
    click A_Name "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/cv_name.joblib"
    click A_Category "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/cv_category.joblib"
    click A_Cond "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/ohe_condition.joblib"
    click A_Brand "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/lb_brand.joblib"

    click Notebook "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/Price_recommendation_for_Online_Sellers.ipynb"
    click DataSet "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/dataset/sample_train.tsv"

    click Reqs "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/requirements.txt"
    click DeployDoc "https://github.com/aswajithb/ecommerce-smart-pricing-engine/blob/main/DEPLOYMENT.md"

    %% ========= Styles =========
    classDef client fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#0b2a6f
    classDef ui fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#083344
    classDef app fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#052e16
    classDef logic fill:#bbf7d0,stroke:#15803d,stroke-width:1.5px,color:#052e16
    classDef ml fill:#f3e8ff,stroke:#7c3aed,stroke-width:1.5px,color:#2e1065
    classDef artifact fill:#ede9fe,stroke:#6d28d9,stroke-width:1.2px,color:#2e1065
    classDef external fill:#ffedd5,stroke:#f97316,stroke-width:1.5px,color:#7c2d12
    classDef infra fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
    classDef data fill:#fef9c3,stroke:#ca8a04,stroke-width:1.5px,color:#713f12
    classDef offline fill:#fff7ed,stroke:#c2410c,stroke-width:1.5px,color:#7c2d12
    classDef ops fill:#f1f5f9,stroke:#475569,stroke-width:1.5px,color:#0f172a
```
