# yufanpeter/e-commerce-ai-agent architecture

> Architecture diagram of the GitHub repository yufanpeter/e-commerce-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yufanpeter/e-commerce-ai-agent
- Repository: https://github.com/yufanpeter/e-commerce-ai-agent

## Overview

CartPilot is a conversational shopping assistant: the iOS user sends text, voice, or image input; the backend routes each turn to a shopping tool, retrieves grounded product results when needed, and returns structured results and composed responses. Users can refine or compare recommendations, inspect products, and manage a persistent cart and preferences. The README documents the major capabilities; sampled excerpts confirm key orchestration and retrieval ownership, but do not expose every tool or route implementation.

Main entry points: [`client/AIShoppingGuide/FrontendServices.swift`](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/FrontendServices.swift) (Frontend Services), [`backend/api/main.py`](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/api/main.py) (FastAPI Routes), [`backend/agent/orchestrator.py`](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/agent/orchestrator.py) (Turn Orchestrator), [`backend/search/search_service.py`](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/search/search_service.py) (Hybrid Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["iOS Client"]
  node_ios["SwiftUI App"]
  node_guide["Shopping Guide<br/>[GuideView.swift]"]
  node_frontend["Frontend Services"]
  node_detail["Product Details"]
  node_comparison["Comparison View"]
  node_cartview["Cart View<br/>[CartView.swift]"]
  node_preferences["Preference View"]
end

subgraph group_api["HTTP API"]
  node_fastapi["FastAPI Routes<br/>[main.py]"]
  node_productroutes["Product Routes<br/>[products.py]"]
end

subgraph group_agent["Agent Workflow"]
  node_orchestrator["Turn Orchestrator<br/>[orchestrator.py]"]
  node_router["Intent Router<br/>[intent_router.py]"]
  node_tools["Shopping Tools"]
  node_composer["Answer Composer<br/>[composer.py]"]
end

subgraph group_retrieval["Search and Retrieval"]
  node_searchservice["Hybrid Search<br/>[search_service.py]"]
  node_understanding["Query Understanding"]
  node_parser["LLM Query Parser<br/>[llm_parser.py]"]
  node_retriever["Chroma Retriever<br/>[retriever.py]"]
  node_reranker["Optional Reranker<br/>[reranker.py]"]
end

subgraph group_state["Product and State"]
  node_chroma[("Chroma Index<br/>[chroma_store.py]")]
  node_productstore[("Product Store<br/>[product_store.py]")]
  node_sessionstore[("Session Store<br/>[session_store.py]")]
  node_cartstore[("Cart Store<br/>[cart_store.py]")]
  node_memorystore[("Preference Memory")]
end

node_shopper(("Shopper"))
node_llm{{"Chat Model API"}}
node_embedding{{"Embedding API"}}
node_rerankapi{{"Reranking API"}}

node_shopper -->|"uses"| node_ios
node_ios -->|"shows"| node_guide
node_guide -->|"requests"| node_frontend
node_frontend -->|"REST and SSE"| node_fastapi
node_fastapi -->|"handles turns"| node_orchestrator
node_orchestrator -->|"routes intent"| node_router
node_router -->|"classifies intent"| node_llm
node_orchestrator -->|"dispatches tool"| node_tools
node_orchestrator -->|"composes response"| node_composer
node_composer -->|"generates narrative"| node_llm
node_tools -->|"searches products"| node_searchservice
node_searchservice -->|"interprets query"| node_understanding
node_understanding -->|"extracts intent"| node_parser
node_parser -->|"parses query"| node_llm
node_searchservice -->|"retrieves chunks"| node_retriever
node_retriever -->|"queries vectors"| node_chroma
node_retriever -->|"embeds query"| node_embedding
node_searchservice -.->|"optionally reranks"| node_reranker
node_reranker -.->|"scores candidates"| node_rerankapi
node_searchservice -->|"grounds product facts"| node_productstore
node_tools -->|"reads product data"| node_productstore
node_orchestrator -->|"persists sessions"| node_sessionstore
node_tools -->|"updates cart"| node_cartstore
node_fastapi -->|"reads cart"| node_cartstore
node_fastapi -->|"mounts routes"| node_productroutes
node_productroutes -->|"reads product data"| node_productstore
node_fastapi -->|"reads preferences"| node_memorystore
node_shopper -->|"inspects products"| node_detail
node_shopper -->|"compares products"| node_comparison
node_shopper -->|"manages cart"| node_cartview
node_shopper -->|"sets preferences"| node_preferences
node_detail -->|"fetches details"| node_frontend
node_comparison -->|"requests comparison"| node_frontend
node_cartview -->|"loads cart"| node_frontend
node_preferences -->|"loads preferences"| node_frontend

click node_ios "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/AIShoppingGuideApp.swift"
click node_guide "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/GuideView.swift"
click node_frontend "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/FrontendServices.swift"
click node_detail "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/ProductDetailView.swift"
click node_comparison "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/ComparisonView.swift"
click node_cartview "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/CartView.swift"
click node_preferences "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/PreferenceView.swift"
click node_fastapi "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/api/main.py"
click node_productroutes "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/api/products.py"
click node_orchestrator "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/agent/orchestrator.py"
click node_router "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/agent/intent_router.py"
click node_tools "https://github.com/yufanpeter/e-commerce-ai-agent/tree/main/backend/agent/tools"
click node_composer "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/agent/composer.py"
click node_searchservice "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/search/search_service.py"
click node_understanding "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/search/query_understanding.py"
click node_parser "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/search/llm_parser.py"
click node_retriever "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/rag/retriever.py"
click node_reranker "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/rag/reranker.py"
click node_chroma "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/rag/chroma_store.py"
click node_productstore "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/store/product_store.py"
click node_sessionstore "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/store/session_store.py"
click node_cartstore "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/store/cart_store.py"
click node_memorystore "https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/store/user_memory_store.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_ios,node_guide,node_frontend,node_detail,node_comparison,node_cartview,node_preferences toneBlue
class node_fastapi,node_productroutes toneAmber
class node_orchestrator,node_router,node_tools,node_composer,node_llm,node_embedding,node_rerankapi toneMint
class node_searchservice,node_understanding,node_parser,node_retriever,node_reranker toneRose
class node_chroma,node_productstore,node_sessionstore,node_cartstore,node_memorystore,node_shopper toneIndigo
```

## Components

### iOS Client

- [SwiftUI App](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/AIShoppingGuideApp.swift): `client/AIShoppingGuide/AIShoppingGuideApp.swift`
- [Shopping Guide](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/GuideView.swift): `client/AIShoppingGuide/GuideView.swift`
- [Frontend Services](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/FrontendServices.swift): `client/AIShoppingGuide/FrontendServices.swift`
- [Product Details](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/ProductDetailView.swift): `client/AIShoppingGuide/ProductDetailView.swift`
- [Comparison View](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/ComparisonView.swift): `client/AIShoppingGuide/ComparisonView.swift`
- [Cart View](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/CartView.swift): `client/AIShoppingGuide/CartView.swift`
- [Preference View](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/client/AIShoppingGuide/PreferenceView.swift): `client/AIShoppingGuide/PreferenceView.swift`

### HTTP API

- [FastAPI Routes](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/api/main.py): `backend/api/main.py`
- [Product Routes](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/api/products.py): `backend/api/products.py`

### Agent Workflow

- [Turn Orchestrator](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/agent/orchestrator.py): `backend/agent/orchestrator.py`
- [Intent Router](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/agent/intent_router.py): `backend/agent/intent_router.py`
- [Shopping Tools](https://github.com/yufanpeter/e-commerce-ai-agent/tree/main/backend/agent/tools): `backend/agent/tools`
- [Answer Composer](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/agent/composer.py): `backend/agent/composer.py`

### Search and Retrieval

- [Hybrid Search](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/search/search_service.py): `backend/search/search_service.py`
- [Query Understanding](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/search/query_understanding.py): `backend/search/query_understanding.py`
- [LLM Query Parser](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/search/llm_parser.py): `backend/search/llm_parser.py`
- [Chroma Retriever](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/rag/retriever.py): `backend/rag/retriever.py`
- [Optional Reranker](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/rag/reranker.py): `backend/rag/reranker.py`

### Product and State

- [Chroma Index](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/rag/chroma_store.py): `backend/rag/chroma_store.py`
- [Product Store](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/store/product_store.py): `backend/store/product_store.py`
- [Session Store](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/store/session_store.py): `backend/store/session_store.py`
- [Cart Store](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/store/cart_store.py): `backend/store/cart_store.py`
- [Preference Memory](https://github.com/yufanpeter/e-commerce-ai-agent/blob/main/backend/store/user_memory_store.py): `backend/store/user_memory_store.py`

### Other components

- **Shopper**
- **Chat Model API**
- **Embedding API**
- **Reranking API**

## Connections

- Shopper → SwiftUI App: uses
- SwiftUI App → Shopping Guide: shows
- Shopping Guide → Frontend Services: requests
- Frontend Services → FastAPI Routes: REST and SSE
- FastAPI Routes → Turn Orchestrator: handles turns
- Turn Orchestrator → Intent Router: routes intent
- Intent Router → Chat Model API: classifies intent
- Turn Orchestrator → Shopping Tools: dispatches tool
- Turn Orchestrator → Answer Composer: composes response
- Answer Composer → Chat Model API: generates narrative
- Shopping Tools → Hybrid Search: searches products
- Hybrid Search → Query Understanding: interprets query
- Query Understanding → LLM Query Parser: extracts intent
- LLM Query Parser → Chat Model API: parses query
- Hybrid Search → Chroma Retriever: retrieves chunks
- Chroma Retriever → Chroma Index: queries vectors
- Chroma Retriever → Embedding API: embeds query
- Hybrid Search → Optional Reranker: optionally reranks
- Optional Reranker → Reranking API: scores candidates
- Hybrid Search → Product Store: grounds product facts
- Shopping Tools → Product Store: reads product data
- Turn Orchestrator → Session Store: persists sessions
- Shopping Tools → Cart Store: updates cart
- FastAPI Routes → Cart Store: reads cart
- FastAPI Routes → Product Routes: mounts routes
- Product Routes → Product Store: reads product data
- FastAPI Routes → Preference Memory: reads preferences
- Shopper → Product Details: inspects products
- Shopper → Comparison View: compares products
- Shopper → Cart View: manages cart
- Shopper → Preference View: sets preferences
- Product Details → Frontend Services: fetches details
- Comparison View → Frontend Services: requests comparison
- Cart View → Frontend Services: loads cart
- Preference View → Frontend Services: loads preferences