# jayxdev/smart-shopping architecture

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

- Interactive diagram: https://gitdiagram.com/jayxdev/smart-shopping
- Repository: https://github.com/jayxdev/smart-shopping

## Overview

Smart Shopping serves two user-facing workflows: a personalized recommendation app and an analytics dashboard. In the app, customer and product CSVs are loaded, customer segments and product records are prepared, and a selected customer receives ranked recommendations with an optional Ollama-generated description; recommendation history is persisted in SQLite. The dashboard independently builds segments, profiles them, and generates targeting strategies. The graph follows the shown calls and documented capabilities; the dashboard excerpt is partial, so internal details beyond it are not inferred.

Main entry points: [`main.py`](https://github.com/jayxdev/smart-shopping/blob/main/main.py) (Shopping App), [`dashboard.py`](https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py) (Analytics Dashboard), [`ecommerce.db`](https://github.com/jayxdev/smart-shopping/blob/main/ecommerce.db) (SQLite Database), [`agents/recommendation_agent.py`](https://github.com/jayxdev/smart-shopping/blob/main/agents/recommendation_agent.py) (Recommendation Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_recommendation_app["Recommendation App"]
  node_main_app["Shopping App<br/>[main.py]"]
  node_recommendation_display["Recommendation Results<br/>[main.py]"]
  node_history_view["Recommendation History<br/>[main.py]"]
end

subgraph group_recommendation_engine["Recommendation Engine"]
  node_customer_agent["Customer Segmentation<br/>[customer_agent.py]"]
  node_product_agent["Product Catalog Setup<br/>[product_agent.py]"]
  node_recommendation_agent["Recommendation Engine"]
end

subgraph group_analytics_dashboard["Analytics Dashboard"]
  node_dashboard_app["Analytics Dashboard<br/>[dashboard.py]"]
  node_dashboard_features["Feature Preparation<br/>[dashboard.py]"]
  node_dashboard_clusters["Dynamic Clustering<br/>[dashboard.py]"]
  node_cluster_profiles["Cluster Profiles<br/>[dashboard.py]"]
  node_targeting_strategies["Targeting Strategies<br/>[dashboard.py]"]
end

subgraph group_data_persistence["Data and Persistence"]
  node_data_loader["CSV Data Loader<br/>[data_utils.py]"]
  node_source_csvs["Customer and Product CSVs"]
  node_sqlite_db[("SQLite Database<br/>[ecommerce.db]")]
end

node_shopper(("Shopper"))
node_ollama["Ollama LLM"]

node_shopper -->|"selects customer"| node_main_app
node_main_app -->|"loads CSVs"| node_data_loader
node_data_loader -->|"reads"| node_source_csvs
node_main_app -->|"segments customers"| node_customer_agent
node_customer_agent -->|"writes clusters"| node_sqlite_db
node_main_app -->|"prepares products"| node_product_agent
node_product_agent -->|"stores product data"| node_sqlite_db
node_shopper -->|"requests recommendations"| node_main_app
node_main_app -->|"requests ranking"| node_recommendation_agent
node_recommendation_agent -->|"reads clusters and similarity"| node_sqlite_db
node_recommendation_agent -->|"stores recommendations"| node_sqlite_db
node_recommendation_agent -.->|"requests description"| node_ollama
node_main_app -.->|"starts service"| node_ollama
node_main_app -->|"displays results"| node_recommendation_display
node_main_app -->|"requests segmentation plot"| node_customer_agent
node_main_app -->|"queries history"| node_history_view
node_history_view -->|"reads history"| node_sqlite_db
node_shopper -->|"explores analytics"| node_dashboard_app
node_dashboard_app -->|"loads data"| node_source_csvs
node_dashboard_app -->|"prepares inputs"| node_dashboard_features
node_dashboard_app -->|"creates clusters"| node_dashboard_clusters
node_dashboard_clusters -->|"uses features"| node_dashboard_features
node_dashboard_app -->|"profiles segments"| node_cluster_profiles
node_dashboard_app -->|"generates strategies"| node_targeting_strategies

click node_main_app "https://github.com/jayxdev/smart-shopping/blob/main/main.py"
click node_data_loader "https://github.com/jayxdev/smart-shopping/blob/main/utils/data_utils.py"
click node_customer_agent "https://github.com/jayxdev/smart-shopping/blob/main/agents/customer_agent.py"
click node_product_agent "https://github.com/jayxdev/smart-shopping/blob/main/agents/product_agent.py"
click node_recommendation_agent "https://github.com/jayxdev/smart-shopping/blob/main/agents/recommendation_agent.py"
click node_recommendation_display "https://github.com/jayxdev/smart-shopping/blob/main/main.py"
click node_history_view "https://github.com/jayxdev/smart-shopping/blob/main/main.py"
click node_source_csvs "https://github.com/jayxdev/smart-shopping/tree/main/data"
click node_sqlite_db "https://github.com/jayxdev/smart-shopping/blob/main/ecommerce.db"
click node_dashboard_app "https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py"
click node_dashboard_features "https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py"
click node_dashboard_clusters "https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py"
click node_cluster_profiles "https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py"
click node_targeting_strategies "https://github.com/jayxdev/smart-shopping/blob/main/dashboard.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_main_app,node_recommendation_display,node_history_view toneBlue
class node_customer_agent,node_product_agent,node_recommendation_agent toneAmber
class node_dashboard_app,node_dashboard_features,node_dashboard_clusters,node_cluster_profiles,node_targeting_strategies toneMint
class node_data_loader,node_source_csvs,node_sqlite_db toneRose
class node_shopper,node_ollama toneIndigo
```

## Components

### Recommendation App

- [Shopping App](https://github.com/jayxdev/smart-shopping/blob/main/main.py): `main.py`
- [Recommendation Results](https://github.com/jayxdev/smart-shopping/blob/main/main.py): `main.py`
- [Recommendation History](https://github.com/jayxdev/smart-shopping/blob/main/main.py): `main.py`

### Recommendation Engine

- [Customer Segmentation](https://github.com/jayxdev/smart-shopping/blob/main/agents/customer_agent.py): `agents/customer_agent.py`
- [Product Catalog Setup](https://github.com/jayxdev/smart-shopping/blob/main/agents/product_agent.py): `agents/product_agent.py`
- [Recommendation Engine](https://github.com/jayxdev/smart-shopping/blob/main/agents/recommendation_agent.py): `agents/recommendation_agent.py`

### Analytics Dashboard

- [Analytics Dashboard](https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py): `dashboard.py`
- [Feature Preparation](https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py): `dashboard.py`
- [Dynamic Clustering](https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py): `dashboard.py`
- [Cluster Profiles](https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py): `dashboard.py`
- [Targeting Strategies](https://github.com/jayxdev/smart-shopping/blob/main/dashboard.py): `dashboard.py`

### Data and Persistence

- [CSV Data Loader](https://github.com/jayxdev/smart-shopping/blob/main/utils/data_utils.py): `utils/data_utils.py`
- [Customer and Product CSVs](https://github.com/jayxdev/smart-shopping/tree/main/data): `data`
- [SQLite Database](https://github.com/jayxdev/smart-shopping/blob/main/ecommerce.db): `ecommerce.db`

### Other components

- **Shopper**
- **Ollama LLM**

## Connections

- Shopper → Shopping App: selects customer (evidence: `README.md`)
- Shopping App → CSV Data Loader: loads CSVs (evidence: `main.py`)
- CSV Data Loader → Customer and Product CSVs: reads (evidence: `utils/data_utils.py`)
- Shopping App → Customer Segmentation: segments customers (evidence: `main.py`)
- Customer Segmentation → SQLite Database: writes clusters (evidence: `agents/customer_agent.py`)
- Shopping App → Product Catalog Setup: prepares products (evidence: `main.py`)
- Product Catalog Setup → SQLite Database: stores product data (evidence: `agents/product_agent.py`)
- Shopper → Shopping App: requests recommendations (evidence: `README.md`)
- Shopping App → Recommendation Engine: requests ranking (evidence: `main.py`)
- Recommendation Engine → SQLite Database: reads clusters and similarity (evidence: `agents/recommendation_agent.py`)
- Recommendation Engine → SQLite Database: stores recommendations (evidence: `agents/recommendation_agent.py`)
- Recommendation Engine → Ollama LLM: requests description (evidence: `agents/recommendation_agent.py`)
- Shopping App → Ollama LLM: starts service (evidence: `main.py`)
- Shopping App → Recommendation Results: displays results (evidence: `main.py`)
- Shopping App → Customer Segmentation: requests segmentation plot (evidence: `main.py`)
- Shopping App → Recommendation History: queries history (evidence: `main.py`)
- Recommendation History → SQLite Database: reads history (evidence: `main.py`)
- Shopper → Analytics Dashboard: explores analytics (evidence: `README.md`)
- Analytics Dashboard → Customer and Product CSVs: loads data (evidence: `README.md`)
- Analytics Dashboard → Feature Preparation: prepares inputs (evidence: `dashboard.py`)
- Analytics Dashboard → Dynamic Clustering: creates clusters (evidence: `dashboard.py`)
- Dynamic Clustering → Feature Preparation: uses features (evidence: `dashboard.py`)
- Analytics Dashboard → Cluster Profiles: profiles segments (evidence: `dashboard.py`)
- Analytics Dashboard → Targeting Strategies: generates strategies (evidence: `dashboard.py`)
