# hhaarrss/dynamic-pricing-engine architecture

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

- Interactive diagram: https://gitdiagram.com/hhaarrss/dynamic-pricing-engine
- Repository: https://github.com/hhaarrss/dynamic-pricing-engine

## Overview

This is a dynamic-pricing engine: product and market inputs lead to price recommendations from a LinUCB agent, served through FastAPI and presented in a Streamlit dashboard. A separate data workflow scrapes Amazon listings, cleans them, and supports feature engineering; the README also documents XGBoost demand forecasting, SHAP explanations, MLflow tracking, and strategy backtesting. The graph distinguishes documented capabilities from source-confirmed calls. Some feature-pipeline wiring and backtester integration are not shown in the excerpts, so those links are omitted rather than inferred.

Main entry points: [`data/processed/features.csv`](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/processed/features.csv) (Engineered Features), [`api/main.py`](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/main.py) (Pricing API), [`api/predict.py`](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/predict.py) (Pricing Predictor), [`scraper/amazon_scraper.py`](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/scraper/amazon_scraper.py) (Amazon Scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Market Data"]
  node_scraper["Amazon Scraper<br/>[amazon_scraper.py]"]
  node_rawdb[("Raw Price Store<br/>[database.db]")]
  node_cleaner["Data Cleaner<br/>[cleaner.py]"]
  node_scheduler["Scrape Scheduler<br/>[scheduler.py]"]
  node_cleaned["Cleaned Prices<br/>[cleaned_prices.csv]"]
end

subgraph group_features["Feature Engineering"]
  node_demandfeatures["Demand Signals<br/>[demand_signals.py]"]
  node_competitorfeatures["Competitor Gaps<br/>[competitor_gap.py]"]
  node_elasticity["Price Elasticity<br/>[elasticity.py]"]
  node_featuredata["Engineered Features<br/>[features.csv]"]
end

subgraph group_models["Modeling"]
  node_forecaster["Demand Forecaster"]
  node_rl["LinUCB Agent<br/>[rl_agent.py]"]
end

subgraph group_serving["Price Serving"]
  node_api["Pricing API<br/>[main.py]"]
  node_predictor["Pricing Predictor<br/>[predict.py]"]
  node_schemas["API Schemas<br/>[schemas.py]"]
  node_health["Health Endpoint<br/>[health.py]"]
  node_dashboard["Pricing Dashboard<br/>[app.py]"]
end

subgraph group_analysis["Strategy Analysis"]
  node_backtester["Strategy Backtester<br/>[backtester.py]"]
  node_mlflow[("MLflow Tracking")]
  node_shapdata["SHAP Results<br/>[shap_values.csv]"]
end

node_operator(("Pricing User"))
node_amazon{{"Amazon Listings"}}

node_amazon -->|"scrapes"| node_scraper
node_scheduler -->|"runs"| node_scraper
node_scheduler -->|"runs"| node_cleaner
node_scraper -->|"writes listings"| node_rawdb
node_cleaner -->|"reads"| node_rawdb
node_cleaner -->|"writes"| node_cleaned
node_scraper -->|"followed by"| node_cleaner
node_cleaned -->|"input"| node_demandfeatures
node_cleaned -->|"input"| node_competitorfeatures
node_demandfeatures -->|"updates"| node_featuredata
node_competitorfeatures -->|"updates"| node_featuredata
node_elasticity -.->|"writes"| node_featuredata
node_featuredata -->|"trains from"| node_forecaster
node_forecaster -->|"logs experiments"| node_mlflow
node_forecaster -->|"writes explanations"| node_shapdata
node_featuredata -->|"trains from"| node_rl
node_featuredata -->|"evaluates strategies"| node_backtester
node_operator -->|"submits inputs"| node_dashboard
node_dashboard -->|"requests price"| node_api
node_dashboard -->|"checks health"| node_health
node_api -->|"calls"| node_predictor
node_api -->|"registers route"| node_health
node_api -->|"validates"| node_schemas
node_predictor -->|"uses types"| node_schemas
node_predictor -->|"scores actions"| node_rl
node_predictor -->|"loads features"| node_featuredata

click node_scraper "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/scraper/amazon_scraper.py"
click node_rawdb "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/database.db"
click node_cleaner "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/scraper/cleaner.py"
click node_scheduler "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/scraper/scheduler.py"
click node_cleaned "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/processed/cleaned_prices.csv"
click node_demandfeatures "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/features/demand_signals.py"
click node_competitorfeatures "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/features/competitor_gap.py"
click node_elasticity "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/features/elasticity.py"
click node_featuredata "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/processed/features.csv"
click node_forecaster "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/models/demand_forecaster.py"
click node_rl "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/models/rl_agent.py"
click node_backtester "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/models/backtester.py"
click node_mlflow "https://github.com/hhaarrss/dynamic-pricing-engine/tree/master/mlflow_tracking"
click node_shapdata "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/processed/shap_values.csv"
click node_api "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/main.py"
click node_predictor "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/predict.py"
click node_schemas "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/schemas.py"
click node_health "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/health.py"
click node_dashboard "https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/dashboard/app.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_scraper,node_rawdb,node_cleaner,node_scheduler,node_cleaned,node_operator toneBlue
class node_demandfeatures,node_competitorfeatures,node_elasticity,node_featuredata toneAmber
class node_forecaster,node_rl toneMint
class node_api,node_predictor,node_schemas,node_health,node_dashboard toneRose
class node_backtester,node_mlflow,node_shapdata,node_amazon toneIndigo
```

## Components

### Market Data

- [Amazon Scraper](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/scraper/amazon_scraper.py): `scraper/amazon_scraper.py`
- [Raw Price Store](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/database.db): `data/database.db`
- [Data Cleaner](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/scraper/cleaner.py): `scraper/cleaner.py`
- [Scrape Scheduler](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/scraper/scheduler.py): `scraper/scheduler.py`
- [Cleaned Prices](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/processed/cleaned_prices.csv): `data/processed/cleaned_prices.csv`

### Feature Engineering

- [Demand Signals](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/features/demand_signals.py): `features/demand_signals.py`
- [Competitor Gaps](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/features/competitor_gap.py): `features/competitor_gap.py`
- [Price Elasticity](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/features/elasticity.py): `features/elasticity.py`
- [Engineered Features](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/processed/features.csv): `data/processed/features.csv`

### Modeling

- [Demand Forecaster](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/models/demand_forecaster.py): `models/demand_forecaster.py`
- [LinUCB Agent](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/models/rl_agent.py): `models/rl_agent.py`

### Price Serving

- [Pricing API](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/main.py): `api/main.py`
- [Pricing Predictor](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/predict.py): `api/predict.py`
- [API Schemas](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/schemas.py): `api/schemas.py`
- [Health Endpoint](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/api/health.py): `api/health.py`
- [Pricing Dashboard](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/dashboard/app.py): `dashboard/app.py`

### Strategy Analysis

- [Strategy Backtester](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/models/backtester.py): `models/backtester.py`
- [MLflow Tracking](https://github.com/hhaarrss/dynamic-pricing-engine/tree/master/mlflow_tracking): `mlflow_tracking`
- [SHAP Results](https://github.com/hhaarrss/dynamic-pricing-engine/blob/master/data/processed/shap_values.csv): `data/processed/shap_values.csv`

### Other components

- **Pricing User**
- **Amazon Listings**

## Connections

- Amazon Listings → Amazon Scraper: scrapes (evidence: `README.md`)
- Scrape Scheduler → Amazon Scraper: runs (evidence: `scraper/scheduler.py`)
- Scrape Scheduler → Data Cleaner: runs (evidence: `scraper/scheduler.py`)
- Amazon Scraper → Raw Price Store: writes listings (evidence: `scraper/amazon_scraper.py`)
- Data Cleaner → Raw Price Store: reads (evidence: `scraper/cleaner.py`)
- Data Cleaner → Cleaned Prices: writes (evidence: `scraper/cleaner.py`)
- Amazon Scraper → Data Cleaner: followed by (evidence: `scraper/scheduler.py`)
- Cleaned Prices → Demand Signals: input (evidence: `features/demand_signals.py`)
- Cleaned Prices → Competitor Gaps: input (evidence: `features/competitor_gap.py`)
- Demand Signals → Engineered Features: updates (evidence: `features/demand_signals.py`)
- Competitor Gaps → Engineered Features: updates (evidence: `features/competitor_gap.py`)
- Price Elasticity → Engineered Features: writes
- Engineered Features → Demand Forecaster: trains from (evidence: `models/demand_forecaster.py`)
- Demand Forecaster → MLflow Tracking: logs experiments (evidence: `models/demand_forecaster.py`)
- Demand Forecaster → SHAP Results: writes explanations (evidence: `models/demand_forecaster.py`)
- Engineered Features → LinUCB Agent: trains from (evidence: `models/rl_agent.py`)
- Engineered Features → Strategy Backtester: evaluates strategies (evidence: `README.md`)
- Pricing User → Pricing Dashboard: submits inputs (evidence: `dashboard/app.py`)
- Pricing Dashboard → Pricing API: requests price (evidence: `dashboard/app.py`)
- Pricing Dashboard → Health Endpoint: checks health (evidence: `dashboard/app.py`)
- Pricing API → Pricing Predictor: calls (evidence: `api/main.py`)
- Pricing API → Health Endpoint: registers route (evidence: `api/main.py`)
- Pricing API → API Schemas: validates (evidence: `api/main.py`)
- Pricing Predictor → API Schemas: uses types (evidence: `api/predict.py`)
- Pricing Predictor → LinUCB Agent: scores actions (evidence: `api/predict.py`)
- Pricing Predictor → Engineered Features: loads features (evidence: `api/predict.py`)
