# hoanganhvu123/shoppinggpt architecture

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

- Interactive diagram: https://gitdiagram.com/hoanganhvu123/shoppinggpt
- Repository: https://github.com/hoanganhvu123/shoppinggpt

## Overview

#### 1. Purpose and entry points
ShoppingGPT is a Python shopping-assistant chatbot: it routes a user query, retrieves product/policy context when relevant, and uses Google Gemini to respond. The runnable web entry point is `app.py`; `main.py` is a secondary application/orchestration entry point. The browser UI is served from `templates/index.html` with styling in `static/style.css`.

#### 2. Web request boundary
The Flask layer accepts chat input and returns assistant output, separating the browser-facing interface from LLM and retrieval logic. Its primary assets are:
- `app.py`
- `templates/index.html`
- `static/style.css`

#### 3. Query orchestration and conversational path
The core domain package coordinates routing, chat generation, agent behavior, and conversation state. General conversation is handled through a chain backed by Gemini and conversation memory; shopping-oriented requests are delegated to the agent/tools.
- `shoppinggpt/chain.py`
- `shoppinggpt/agent.py`
- `shoppinggpt/config.py`

#### 4. Semantic routing/classification
Before expensive retrieval or agent execution, the router distinguishes chitchat from product-related intent. The repository supports multiple classification approaches: semantic-router embeddings, cosine-similarity routing, and a fine-tuned Hugging Face classifier. This is the key control-flow fork between the chitchat chain and shopping agent.
- `shoppinggpt/router/lib_semantic_router.py`
- `shoppinggpt/router/consine_algo_semantic.py`
- `shoppinggpt/router/pretrain_model_for_route.py`

#### 5. Product retrieval path
Product questions use SQLite-backed search with case-insensitive/partial matching, then provide structured inventory results to the agent/LLM for grounded responses. Product inventory is persisted separately from source CSV input.
- `shoppinggpt/tool/product_search.py`
- `data/products.db`
- `data/products.csv`

#### 6. Policy RAG path
Policy questions use vector similarity retrieval over a persisted FAISS datastore. Retrieved company-policy passages are injected into the response-generation context rather than relying only on model knowledge.
- `shoppinggpt/tool/policy_search.py`
- `data/datastore/index.faiss`
- `data/datastore/index.pkl`

#### 7. Runtime, models, and deployment
The system runs as a Flask/Python service with dependencies declared in `requirements.txt`. It requires `GOOGLE_API_KEY` (documented in `.env.example`) for Google Generative AI: Gemini 1.5 Flash for generation and Google embeddings for routing/retrieval. A remote Hugging Face model, `hang1704/opendaisy`, is an additional classification dependency. Production deployment automation is defined in `.github/workflows/deploy-production.yml`.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web UI"]
  node_browser["Browser chat UI<br/>HTML/CSS<br/>[index.html]"]
  node_styles["Chat styling<br/>CSS<br/>[style.css]"]
  node_flask["Flask app<br/>request boundary<br/>[app.py]"]
end

subgraph group_core["Conversation Core"]
  node_main["Secondary entry point<br/>orchestration entry<br/>[main.py]"]
  node_chain["Chat chain<br/>conversation generation<br/>[chain.py]"]
  node_agent["Shopping agent<br/>tool-using agent<br/>[agent.py]"]
  node_config["Model configuration<br/>runtime config<br/>[config.py]"]
end

subgraph group_routing["Intent Routing"]
  node_semantic_router["Embedding router<br/>semantic classifier"]
  node_cosine_router["Cosine router<br/>similarity classifier"]
  node_hf_router["Fine-tuned router<br/>Hugging Face classifier"]
end

subgraph group_retrieval["Grounded Retrieval"]
  node_product_search["Product search<br/>inventory retrieval tool<br/>[product_search.py]"]
  node_products_db[("Product inventory<br/>SQLite database<br/>[products.db]")]
  node_products_csv["Product source data<br/>CSV import<br/>[products.csv]"]
  node_policy_search["Policy search<br/>RAG retrieval tool<br/>[policy_search.py]"]
  node_faiss_index[("Policy vector index<br/>FAISS datastore<br/>[index.faiss]")]
  node_policy_metadata["Policy metadata<br/>FAISS metadata<br/>[index.pkl]"]
end

subgraph group_runtime["Runtime &amp; Deployment"]
  node_gemini{{"Google Gemini<br/>generation and embeddings API"}}
  node_hf_model{{"opendaisy model<br/>remote Hugging Face model"}}
  node_dependencies["Python dependencies<br/>package manifest<br/>[requirements.txt]"]
  node_api_key["Google API key<br/>environment secret<br/>[.env.example]"]
  node_deployment["Production deployment<br/>CI/CD workflow"]
end

node_browser -->|"styled by"| node_styles
node_browser -->|"chat requests"| node_flask
node_flask -->|"invokes"| node_main
node_main -->|"routes query"| node_semantic_router
node_main -.->|"alternative routing"| node_cosine_router
node_main -.->|"alternative routing"| node_hf_router
node_semantic_router -->|"chitchat"| node_chain
node_semantic_router -->|"product or policy intent"| node_agent
node_cosine_router -.->|"chitchat"| node_chain
node_cosine_router -.->|"shopping intent"| node_agent
node_hf_router -.->|"chitchat"| node_chain
node_hf_router -.->|"shopping intent"| node_agent
node_chain -->|"generates response"| node_gemini
node_agent -->|"product lookup"| node_product_search
node_agent -->|"policy lookup"| node_policy_search
node_agent -->|"grounded response"| node_gemini
node_product_search -->|"searches"| node_products_db
node_products_csv -.->|"inventory source"| node_products_db
node_policy_search -->|"similarity search"| node_faiss_index
node_policy_search -->|"loads passages"| node_policy_metadata
node_hf_router -->|"loads classifier"| node_hf_model
node_config -->|"configures"| node_gemini
node_api_key -.->|"authenticates"| node_gemini
node_dependencies -.->|"declares runtime"| node_flask
node_deployment -->|"deploys service"| node_flask

click node_browser "https://github.com/hoanganhvu123/shoppinggpt/blob/main/templates/index.html"
click node_styles "https://github.com/hoanganhvu123/shoppinggpt/blob/main/static/style.css"
click node_flask "https://github.com/hoanganhvu123/shoppinggpt/blob/main/app.py"
click node_main "https://github.com/hoanganhvu123/shoppinggpt/blob/main/main.py"
click node_chain "https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/chain.py"
click node_agent "https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/agent.py"
click node_config "https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/config.py"
click node_semantic_router "https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/router/lib_semantic_router.py"
click node_cosine_router "https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/router/consine_algo_semantic.py"
click node_hf_router "https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/router/pretrain_model_for_route.py"
click node_product_search "https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/tool/product_search.py"
click node_products_db "https://github.com/hoanganhvu123/shoppinggpt/blob/main/data/products.db"
click node_products_csv "https://github.com/hoanganhvu123/shoppinggpt/blob/main/data/products.csv"
click node_policy_search "https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/tool/policy_search.py"
click node_faiss_index "https://github.com/hoanganhvu123/shoppinggpt/blob/main/data/datastore/index.faiss"
click node_policy_metadata "https://github.com/hoanganhvu123/shoppinggpt/blob/main/data/datastore/index.pkl"
click node_dependencies "https://github.com/hoanganhvu123/shoppinggpt/blob/main/requirements.txt"
click node_api_key "https://github.com/hoanganhvu123/shoppinggpt/blob/main/.env.example"
click node_deployment "https://github.com/hoanganhvu123/shoppinggpt/blob/main/.github/workflows/deploy-production.yml"

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_browser,node_styles,node_flask toneBlue
class node_main,node_chain,node_agent,node_config toneAmber
class node_semantic_router,node_cosine_router,node_hf_router toneMint
class node_product_search,node_products_db,node_products_csv,node_policy_search,node_faiss_index,node_policy_metadata toneRose
class node_gemini,node_hf_model,node_dependencies,node_api_key,node_deployment toneIndigo
```

## Components

### Web UI

- [Browser chat UI](https://github.com/hoanganhvu123/shoppinggpt/blob/main/templates/index.html): HTML/CSS · `templates/index.html`
- [Chat styling](https://github.com/hoanganhvu123/shoppinggpt/blob/main/static/style.css): CSS · `static/style.css`
- [Flask app](https://github.com/hoanganhvu123/shoppinggpt/blob/main/app.py): request boundary · Accepts chat input and returns assistant output. · `app.py`

### Conversation Core

- [Secondary entry point](https://github.com/hoanganhvu123/shoppinggpt/blob/main/main.py): orchestration entry · `main.py`
- [Chat chain](https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/chain.py): conversation generation · Uses Gemini with conversation memory for general chat. · `shoppinggpt/chain.py`
- [Shopping agent](https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/agent.py): tool-using agent · Handles shopping requests with grounded tools. · `shoppinggpt/agent.py`
- [Model configuration](https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/config.py): runtime config · `shoppinggpt/config.py`

### Intent Routing

- [Embedding router](https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/router/lib_semantic_router.py): semantic classifier · `shoppinggpt/router/lib_semantic_router.py`
- [Cosine router](https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/router/consine_algo_semantic.py): similarity classifier · `shoppinggpt/router/consine_algo_semantic.py`
- [Fine-tuned router](https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/router/pretrain_model_for_route.py): Hugging Face classifier · `shoppinggpt/router/pretrain_model_for_route.py`

### Grounded Retrieval

- [Product search](https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/tool/product_search.py): inventory retrieval tool · Performs case-insensitive partial product matching. · `shoppinggpt/tool/product_search.py`
- [Product inventory](https://github.com/hoanganhvu123/shoppinggpt/blob/main/data/products.db): SQLite database · `data/products.db`
- [Product source data](https://github.com/hoanganhvu123/shoppinggpt/blob/main/data/products.csv): CSV import · `data/products.csv`
- [Policy search](https://github.com/hoanganhvu123/shoppinggpt/blob/main/shoppinggpt/tool/policy_search.py): RAG retrieval tool · Injects retrieved policy passages into generation context. · `shoppinggpt/tool/policy_search.py`
- [Policy vector index](https://github.com/hoanganhvu123/shoppinggpt/blob/main/data/datastore/index.faiss): FAISS datastore · `data/datastore/index.faiss`
- [Policy metadata](https://github.com/hoanganhvu123/shoppinggpt/blob/main/data/datastore/index.pkl): FAISS metadata · `data/datastore/index.pkl`

### Runtime & Deployment

- **Google Gemini**: generation and embeddings API · Gemini 1.5 Flash generates responses; Google embeddings support routing and retrieval.
- **opendaisy model**: remote Hugging Face model
- [Python dependencies](https://github.com/hoanganhvu123/shoppinggpt/blob/main/requirements.txt): package manifest · `requirements.txt`
- [Google API key](https://github.com/hoanganhvu123/shoppinggpt/blob/main/.env.example): environment secret · `.env.example`
- [Production deployment](https://github.com/hoanganhvu123/shoppinggpt/blob/main/.github/workflows/deploy-production.yml): CI/CD workflow · `.github/workflows/deploy-production.yml`

## Connections

- Browser chat UI → Chat styling: styled by
- Browser chat UI → Flask app: chat requests
- Flask app → Secondary entry point: invokes
- Secondary entry point → Embedding router: routes query
- Secondary entry point → Cosine router: alternative routing
- Secondary entry point → Fine-tuned router: alternative routing
- Embedding router → Chat chain: chitchat
- Embedding router → Shopping agent: product or policy intent
- Cosine router → Chat chain: chitchat
- Cosine router → Shopping agent: shopping intent
- Fine-tuned router → Chat chain: chitchat
- Fine-tuned router → Shopping agent: shopping intent
- Chat chain → Google Gemini: generates response
- Shopping agent → Product search: product lookup
- Shopping agent → Policy search: policy lookup
- Shopping agent → Google Gemini: grounded response
- Product search → Product inventory: searches
- Product source data → Product inventory: inventory source
- Policy search → Policy vector index: similarity search
- Policy search → Policy metadata: loads passages
- Fine-tuned router → opendaisy model: loads classifier
- Model configuration → Google Gemini: configures
- Google API key → Google Gemini: authenticates
- Python dependencies → Flask app: declares runtime
- Production deployment → Flask app: deploys service
