# ren-97/shopmind architecture

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

- Interactive diagram: https://gitdiagram.com/ren-97/shopmind
- Repository: https://github.com/ren-97/shopmind

## Overview

ShopMind is a conversational shopping assistant that grounds recommendations in a product catalog and supports cart-to-checkout actions in chat. The main flow is client → chat API → agent/tool loop → query planning and retrieval → reranking and catalog-backed results → streamed cards. Catalog ingestion and balanced review summaries are separate supporting capabilities. Some API, Android, and retrieval-stage links rely on README or SOURCE INDEX references rather than sampled implementation excerpts; those evidence limits are noted on the relevant edges.

Main entry points: [`server/agent/orchestrator.py`](https://github.com/ren-97/shopmind/blob/main/server/agent/orchestrator.py) (Agent Orchestrator), [`server/storage/catalog_repo.py`](https://github.com/ren-97/shopmind/blob/main/server/storage/catalog_repo.py) (Catalog Repository), [`server/tools/search.py`](https://github.com/ren-97/shopmind/blob/main/server/tools/search.py) (Search Tool), [`server/rag/retrieval/strategies`](https://github.com/ren-97/shopmind/tree/main/server/rag/retrieval/strategies) (Retrieval Strategies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and API"]
  node_android["Android Client"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_sse["SSE Streaming<br/>[sse.py]"]
  node_commerce_api["Cart and Order APIs<br/>[cart.py]"]
end

subgraph group_conversation["Conversation and Tools"]
  node_agent["Agent Orchestrator<br/>[orchestrator.py]"]
  node_session["Session Context<br/>[session_state.py]"]
  node_tool_runtime["Tool Runtime<br/>[base.py]"]
  node_commerce_tools["Commerce Tools<br/>[cart.py]"]
end

subgraph group_discovery["Product Discovery"]
  node_search_tool["Search Tool<br/>[search.py]"]
  node_planner["Query Planner<br/>[planner.py]"]
  node_dispatcher["Retrieval Dispatcher<br/>[dispatcher.py]"]
  node_strategies["Retrieval Strategies"]
  node_embeddings["Embedding Providers"]
  node_reranking["Reranking<br/>[llm_reranker.py]"]
end

subgraph group_data["Catalog and State"]
  node_catalog_repo["Catalog Repository<br/>[catalog_repo.py]"]
  node_catalog_db[("Catalog Database<br/>[models.py]")]
  node_vector_index[("Vector Index<br/>[vector_index.py]")]
  node_user_repo["User State Repository<br/>[user_repo.py]"]
  node_postgres[("Postgres")]
  node_qdrant[("Qdrant")]
end

subgraph group_ingestion["Catalog Ingestion"]
  node_ingestion["Catalog Ingestion<br/>[ingest.py]"]
  node_review_summaries["Review Summaries"]
end

node_shopper(("Shopper"))

node_shopper -->|"asks"| node_android
node_android -->|"sends chat"| node_chat_api
node_chat_api -->|"handles turn"| node_agent
node_agent -->|"loads context"| node_session
node_agent -->|"executes tools"| node_tool_runtime
node_tool_runtime -->|"dispatches"| node_search_tool
node_search_tool -->|"plans query"| node_planner
node_search_tool -->|"dispatches plan"| node_dispatcher
node_dispatcher -->|"selects strategy"| node_strategies
node_strategies -.->|"embeds query"| node_embeddings
node_strategies -->|"retrieves chunks"| node_vector_index
node_strategies -->|"filters catalog"| node_catalog_repo
node_search_tool -->|"reranks hits"| node_reranking
node_reranking -->|"loads product facts"| node_catalog_repo
node_catalog_repo -->|"reads catalog"| node_catalog_db
node_agent -->|"streams events"| node_sse
node_sse -->|"streams cards"| node_android
node_android -->|"manages cart"| node_commerce_api
node_commerce_api -->|"reads and writes"| node_user_repo
node_commerce_api -->|"loads products"| node_catalog_repo
node_agent -.->|"invokes commerce"| node_commerce_tools
node_commerce_tools -.->|"updates user state"| node_user_repo
node_user_repo -.->|"persists state"| node_postgres
node_catalog_db -.->|"stores catalog"| node_postgres
node_vector_index -->|"stores vectors"| node_qdrant
node_ingestion -->|"writes products"| node_catalog_repo
node_ingestion -->|"indexes chunks"| node_vector_index
node_ingestion -->|"summarizes reviews"| node_review_summaries

click node_android "https://github.com/ren-97/shopmind/tree/main/client/ShopMind"
click node_chat_api "https://github.com/ren-97/shopmind/blob/main/server/api/chat.py"
click node_sse "https://github.com/ren-97/shopmind/blob/main/server/api/sse.py"
click node_agent "https://github.com/ren-97/shopmind/blob/main/server/agent/orchestrator.py"
click node_session "https://github.com/ren-97/shopmind/blob/main/server/agent/session_state.py"
click node_tool_runtime "https://github.com/ren-97/shopmind/blob/main/server/tools/base.py"
click node_search_tool "https://github.com/ren-97/shopmind/blob/main/server/tools/search.py"
click node_planner "https://github.com/ren-97/shopmind/blob/main/server/llm/planner.py"
click node_dispatcher "https://github.com/ren-97/shopmind/blob/main/server/rag/retrieval/dispatcher.py"
click node_strategies "https://github.com/ren-97/shopmind/tree/main/server/rag/retrieval/strategies"
click node_embeddings "https://github.com/ren-97/shopmind/tree/main/server/rag/embedders"
click node_reranking "https://github.com/ren-97/shopmind/blob/main/server/rag/reranking/llm_reranker.py"
click node_catalog_repo "https://github.com/ren-97/shopmind/blob/main/server/storage/catalog_repo.py"
click node_catalog_db "https://github.com/ren-97/shopmind/blob/main/server/storage/models.py"
click node_vector_index "https://github.com/ren-97/shopmind/blob/main/server/storage/vector_index.py"
click node_user_repo "https://github.com/ren-97/shopmind/blob/main/server/storage/user_repo.py"
click node_commerce_api "https://github.com/ren-97/shopmind/blob/main/server/api/cart.py"
click node_commerce_tools "https://github.com/ren-97/shopmind/blob/main/server/tools/cart.py"
click node_ingestion "https://github.com/ren-97/shopmind/blob/main/server/indexing/ingest.py"
click node_review_summaries "https://github.com/ren-97/shopmind/blob/main/server/llm/review_summarizer.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_android,node_chat_api,node_sse,node_commerce_api toneBlue
class node_agent,node_session,node_tool_runtime,node_commerce_tools toneAmber
class node_search_tool,node_planner,node_dispatcher,node_strategies,node_embeddings,node_reranking toneMint
class node_catalog_repo,node_catalog_db,node_vector_index,node_user_repo,node_postgres,node_qdrant toneRose
class node_ingestion,node_review_summaries,node_shopper toneIndigo
```

## Components

### Client and API

- [Android Client](https://github.com/ren-97/shopmind/tree/main/client/ShopMind): `client/ShopMind`
- [Chat API](https://github.com/ren-97/shopmind/blob/main/server/api/chat.py): `server/api/chat.py`
- [SSE Streaming](https://github.com/ren-97/shopmind/blob/main/server/api/sse.py): `server/api/sse.py`
- [Cart and Order APIs](https://github.com/ren-97/shopmind/blob/main/server/api/cart.py): `server/api/cart.py`

### Conversation and Tools

- [Agent Orchestrator](https://github.com/ren-97/shopmind/blob/main/server/agent/orchestrator.py): `server/agent/orchestrator.py`
- [Session Context](https://github.com/ren-97/shopmind/blob/main/server/agent/session_state.py): `server/agent/session_state.py`
- [Tool Runtime](https://github.com/ren-97/shopmind/blob/main/server/tools/base.py): `server/tools/base.py`
- [Commerce Tools](https://github.com/ren-97/shopmind/blob/main/server/tools/cart.py): `server/tools/cart.py`

### Product Discovery

- [Search Tool](https://github.com/ren-97/shopmind/blob/main/server/tools/search.py): `server/tools/search.py`
- [Query Planner](https://github.com/ren-97/shopmind/blob/main/server/llm/planner.py): `server/llm/planner.py`
- [Retrieval Dispatcher](https://github.com/ren-97/shopmind/blob/main/server/rag/retrieval/dispatcher.py): `server/rag/retrieval/dispatcher.py`
- [Retrieval Strategies](https://github.com/ren-97/shopmind/tree/main/server/rag/retrieval/strategies): `server/rag/retrieval/strategies`
- [Embedding Providers](https://github.com/ren-97/shopmind/tree/main/server/rag/embedders): `server/rag/embedders`
- [Reranking](https://github.com/ren-97/shopmind/blob/main/server/rag/reranking/llm_reranker.py): `server/rag/reranking/llm_reranker.py`

### Catalog and State

- [Catalog Repository](https://github.com/ren-97/shopmind/blob/main/server/storage/catalog_repo.py): `server/storage/catalog_repo.py`
- [Catalog Database](https://github.com/ren-97/shopmind/blob/main/server/storage/models.py): `server/storage/models.py`
- [Vector Index](https://github.com/ren-97/shopmind/blob/main/server/storage/vector_index.py): `server/storage/vector_index.py`
- [User State Repository](https://github.com/ren-97/shopmind/blob/main/server/storage/user_repo.py): `server/storage/user_repo.py`
- **Postgres**
- **Qdrant**

### Catalog Ingestion

- [Catalog Ingestion](https://github.com/ren-97/shopmind/blob/main/server/indexing/ingest.py): `server/indexing/ingest.py`
- [Review Summaries](https://github.com/ren-97/shopmind/blob/main/server/llm/review_summarizer.py): `server/llm/review_summarizer.py`

### Other components

- **Shopper**

## Connections

- Shopper → Android Client: asks
- Android Client → Chat API: sends chat
- Chat API → Agent Orchestrator: handles turn
- Agent Orchestrator → Session Context: loads context (evidence: `server/agent/orchestrator.py`)
- Agent Orchestrator → Tool Runtime: executes tools (evidence: `server/agent/orchestrator.py`)
- Tool Runtime → Search Tool: dispatches (evidence: `server/tools/base.py`)
- Search Tool → Query Planner: plans query (evidence: `server/tools/search.py`)
- Search Tool → Retrieval Dispatcher: dispatches plan (evidence: `server/tools/search.py`)
- Retrieval Dispatcher → Retrieval Strategies: selects strategy (evidence: `server/rag/retrieval/dispatcher.py`)
- Retrieval Strategies → Embedding Providers: embeds query (evidence: `server/rag/retrieval/strategies/filtered_semantic.py`)
- Retrieval Strategies → Vector Index: retrieves chunks (evidence: `server/rag/retrieval/strategies/filtered_semantic.py`)
- Retrieval Strategies → Catalog Repository: filters catalog (evidence: `server/rag/retrieval/strategies/filtered_semantic.py`)
- Search Tool → Reranking: reranks hits (evidence: `server/tools/search.py`)
- Reranking → Catalog Repository: loads product facts (evidence: `server/rag/reranking/llm_reranker.py`)
- Catalog Repository → Catalog Database: reads catalog (evidence: `server/storage/catalog_repo.py`)
- Agent Orchestrator → SSE Streaming: streams events
- SSE Streaming → Android Client: streams cards
- Android Client → Cart and Order APIs: manages cart
- Cart and Order APIs → User State Repository: reads and writes (evidence: `server/api/cart.py`)
- Cart and Order APIs → Catalog Repository: loads products (evidence: `server/api/cart.py`)
- Agent Orchestrator → Commerce Tools: invokes commerce
- Commerce Tools → User State Repository: updates user state
- User State Repository → Postgres: persists state
- Catalog Database → Postgres: stores catalog
- Vector Index → Qdrant: stores vectors (evidence: `server/storage/vector_index.py`)
- Catalog Ingestion → Catalog Repository: writes products (evidence: `server/indexing/ingest.py`)
- Catalog Ingestion → Vector Index: indexes chunks (evidence: `server/indexing/ingest.py`)
- Catalog Ingestion → Review Summaries: summarizes reviews (evidence: `server/indexing/ingest.py`)