# abhi8893/genai-shopping-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/abhi8893/genai-shopping-assistant
- Repository: https://github.com/abhi8893/genai-shopping-assistant

## Overview

The repository’s product is a conversational shopping assistant backed by an e-commerce API. A user submits a query to the assistant service, which maintains a chat and uses a router to direct requests to product search, shopping actions, or customer service. Product retrieval and cart operations are supported by vector search and the e-commerce backend. The README documents the multi-agent workflow; the sampled service entry point shows chat initialization and integrations, but several agent implementations and runtime connections were not sampled, so those links are omitted or marked unverified.

Main entry points: [`services/shopping-assistant/app.py`](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/shopping-assistant/app.py) (Chat API), [`packages/shopping-assistant/src/shopping_assistant/agent_definitions/router.py`](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/router.py) (Router agent), [`packages/shopping-assistant/src/shopping_assistant/external/ecom_api_client/client.py`](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/external/ecom_api_client/client.py) (E-commerce client), [`services/ecom-backend/domains/products/service.py`](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/products/service.py) (Product service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assistant["Shopping assistant"]
  node_assistant_api["Chat API<br/>[app.py]"]
  node_chat["Chat session<br/>[chat.py]"]
  node_router["Router agent<br/>[router.py]"]
  node_product_agent["Product search<br/>[product_search.py]"]
  node_actions_agent["Shopping actions"]
  node_service_agent["Customer service"]
  node_graph_runtime["Agent graph<br/>[graph.py]"]
end

subgraph group_integrations["Search and integrations"]
  node_retrieval["Product retrieval"]
  node_vector_search[("Vector search")]
  node_ecom_client["E-commerce client<br/>[client.py]"]
end

subgraph group_ecommerce["E-commerce backend"]
  node_ecom_api["E-commerce API<br/>[app.py]"]
  node_product_api["Product API<br/>[router.py]"]
  node_product_service["Product service<br/>[service.py]"]
  node_product_repository["Product repository<br/>[repository.py]"]
  node_cart_service["Cart service<br/>[service.py]"]
  node_user_service["User service<br/>[service.py]"]
end

subgraph group_platform["Shared backend"]
  node_sql_db[("SQL database<br/>[database.py]")]
  node_observability["Observability<br/>[preflight.py]"]
end

node_shopper(("Shopper"))

node_shopper -->|"sends query"| node_assistant_api
node_assistant_api -->|"creates session"| node_chat
node_assistant_api -->|"sets up logging"| node_observability
node_assistant_api -->|"creates client"| node_ecom_client
node_assistant_api -->|"connects client"| node_vector_search
node_router -->|"routes to"| node_product_agent
node_router -->|"routes to"| node_actions_agent
node_router -->|"routes to"| node_service_agent
node_chat -.->|"dispatches via"| node_router
node_product_agent -.->|"uses"| node_retrieval
node_retrieval -.->|"searches"| node_vector_search
node_actions_agent -.->|"uses"| node_ecom_client
node_ecom_client -.->|"calls API"| node_ecom_api
node_ecom_api -->|"mounts routes"| node_product_api
node_product_api -->|"calls"| node_product_service
node_product_service -->|"delegates to"| node_product_repository
node_cart_service -->|"gets products"| node_product_service
node_product_repository -.->|"queries"| node_sql_db
node_user_service -.->|"persists users"| node_sql_db

click node_assistant_api "https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/shopping-assistant/app.py"
click node_chat "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/chat.py"
click node_router "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/router.py"
click node_product_agent "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/product_search.py"
click node_actions_agent "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/shopping_actions.py"
click node_service_agent "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/customer_service.py"
click node_graph_runtime "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/graph/graph.py"
click node_retrieval "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/product_retrieval.py"
click node_ecom_client "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/external/ecom_api_client/client.py"
click node_ecom_api "https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/app.py"
click node_product_api "https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/products/api/router.py"
click node_product_service "https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/products/service.py"
click node_product_repository "https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/products/repository.py"
click node_cart_service "https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/carts/service.py"
click node_user_service "https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/users/service.py"
click node_sql_db "https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/core/database.py"
click node_observability "https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/observability/preflight.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_assistant_api,node_chat,node_router,node_product_agent,node_actions_agent,node_service_agent,node_graph_runtime toneBlue
class node_retrieval,node_vector_search,node_ecom_client toneAmber
class node_ecom_api,node_product_api,node_product_service,node_product_repository,node_cart_service,node_user_service toneMint
class node_sql_db,node_observability toneRose
class node_shopper toneIndigo
```

## Components

### Shopping assistant

- [Chat API](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/shopping-assistant/app.py): `services/shopping-assistant/app.py`
- [Chat session](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/chat.py): `packages/shopping-assistant/src/shopping_assistant/chat.py`
- [Router agent](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/router.py): `packages/shopping-assistant/src/shopping_assistant/agent_definitions/router.py`
- [Product search](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/product_search.py): `packages/shopping-assistant/src/shopping_assistant/agent_definitions/product_search.py`
- [Shopping actions](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/shopping_actions.py): `packages/shopping-assistant/src/shopping_assistant/agent_definitions/shopping_actions.py`
- [Customer service](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/agent_definitions/customer_service.py): `packages/shopping-assistant/src/shopping_assistant/agent_definitions/customer_service.py`
- [Agent graph](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/graph/graph.py): `packages/shopping-assistant/src/shopping_assistant/graph/graph.py`

### Search and integrations

- [Product retrieval](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/product_retrieval.py): `packages/shopping-assistant/src/shopping_assistant/product_retrieval.py`
- **Vector search**
- [E-commerce client](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/external/ecom_api_client/client.py): `packages/shopping-assistant/src/shopping_assistant/external/ecom_api_client/client.py`

### E-commerce backend

- [E-commerce API](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/app.py): `services/ecom-backend/app.py`
- [Product API](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/products/api/router.py): `services/ecom-backend/domains/products/api/router.py`
- [Product service](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/products/service.py): `services/ecom-backend/domains/products/service.py`
- [Product repository](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/products/repository.py): `services/ecom-backend/domains/products/repository.py`
- [Cart service](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/carts/service.py): `services/ecom-backend/domains/carts/service.py`
- [User service](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/domains/users/service.py): `services/ecom-backend/domains/users/service.py`

### Shared backend

- [SQL database](https://github.com/abhi8893/genai-shopping-assistant/blob/main/services/ecom-backend/core/database.py): `services/ecom-backend/core/database.py`
- [Observability](https://github.com/abhi8893/genai-shopping-assistant/blob/main/packages/shopping-assistant/src/shopping_assistant/observability/preflight.py): `packages/shopping-assistant/src/shopping_assistant/observability/preflight.py`

### Other components

- **Shopper**

## Connections

- Shopper → Chat API: sends query (evidence: `services/shopping-assistant/app.py`)
- Chat API → Chat session: creates session (evidence: `services/shopping-assistant/app.py`)
- Chat API → Observability: sets up logging (evidence: `services/shopping-assistant/app.py`)
- Chat API → E-commerce client: creates client (evidence: `services/shopping-assistant/app.py`)
- Chat API → Vector search: connects client (evidence: `services/shopping-assistant/app.py`)
- Router agent → Product search: routes to (evidence: `README.md`)
- Router agent → Shopping actions: routes to (evidence: `README.md`)
- Router agent → Customer service: routes to (evidence: `README.md`)
- Chat session → Router agent: dispatches via
- Product search → Product retrieval: uses
- Product retrieval → Vector search: searches
- Shopping actions → E-commerce client: uses
- E-commerce client → E-commerce API: calls API
- E-commerce API → Product API: mounts routes (evidence: `services/ecom-backend/app.py`)
- Product API → Product service: calls (evidence: `services/ecom-backend/domains/products/api/router.py`)
- Product service → Product repository: delegates to (evidence: `services/ecom-backend/domains/products/service.py`)
- Cart service → Product service: gets products (evidence: `services/ecom-backend/domains/carts/service.py`)
- Product repository → SQL database: queries
- User service → SQL database: persists users
