# sheldon715/shopmate architecture

> Architecture diagram of the GitHub repository sheldon715/shopmate, 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/sheldon715/shopmate
- Repository: https://github.com/sheldon715/shopmate

## Overview

ShopMate is an Android conversational shopping assistant backed by an Express API. The main workflow takes a natural-language request from the Android chat, retrieves grounded catalog facts, generates and streams recommendations, and lets the user continue into product details, cart actions, and a mock checkout. Separate capabilities include image search and speech transcription. PostgreSQL holds structured product, cart, and order facts; Qdrant supports vector retrieval. The README documents the overall RAG and streaming flow; unsampled implementation details are represented only where supported by the repository tree or README.

Main entry points: [`server/src/modules/chat/rag.service.ts`](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/rag.service.ts) (RAG orchestration), [`client/android/app/src/main/java/com/shopmate/app/ui/chat/ChatRecommendationScreen.kt`](https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/ui/chat/ChatRecommendationScreen.kt) (Chat and recommendations), [`server/src/modules/chat/chat.controller.ts`](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/chat.controller.ts) (Chat API), [`client/android/app/src/main/java/com/shopmate/app/data/chat/DefaultChatRepository.kt`](https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/data/chat/DefaultChatRepository.kt) (Chat data client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Android app"]
  node_android["Android app entry<br/>[MainActivity.kt]"]
  node_chatui["Chat and recommendations"]
  node_chatrepo["Chat data client"]
  node_productui["Product details"]
  node_cartui["Cart and checkout UI<br/>[CartScreen.kt]"]
end

subgraph group_api["Backend API"]
  node_chatapi["Chat API<br/>[chat.controller.ts]"]
  node_sse["SSE response writer<br/>[sse-writer.ts]"]
end

subgraph group_discovery["Discovery services"]
  node_rag["RAG orchestration<br/>[rag.service.ts]"]
  node_rewrite["Query rewriting"]
  node_vectorsearch["Vector retrieval"]
  node_qdrant[("Qdrant index<br/>[qdrant.client.ts]")]
  node_llm["LLM providers"]
  node_imageapi["Image search API"]
  node_visualintent["Visual interpretation"]
  node_asr["Speech transcription<br/>[asr.controller.ts]"]
end

subgraph group_commerce["Commerce and data"]
  node_products["Product catalog API<br/>[product.service.ts]"]
  node_postgres[("PostgreSQL facts<br/>[pool.ts]")]
  node_cart["Cart operations<br/>[cart.service.ts]"]
  node_orders["Checkout and orders<br/>[order.service.ts]"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_android
node_android -->|"opens chat"| node_chatui
node_chatui -->|"submits request"| node_chatrepo
node_chatrepo -->|"calls API"| node_chatapi
node_chatapi -->|"runs RAG"| node_rag
node_rag -->|"rewrites query"| node_rewrite
node_rag -->|"retrieves products"| node_vectorsearch
node_vectorsearch -->|"searches vectors"| node_qdrant
node_rag -->|"loads product facts"| node_products
node_products -->|"reads catalog"| node_postgres
node_rag -->|"generates response"| node_llm
node_chatapi -->|"streams events"| node_sse
node_sse -->|"streams response"| node_chatrepo
node_chatui -->|"opens product"| node_productui
node_chatui -->|"requests cart action"| node_cart
node_cartui -->|"manages cart"| node_cart
node_cart -->|"reads and writes"| node_postgres
node_cartui -->|"starts checkout"| node_orders
node_orders -->|"reads and writes"| node_postgres
node_shopper -.->|"provides image"| node_imageapi
node_imageapi -.->|"interprets image"| node_visualintent
node_shopper -.->|"provides speech"| node_asr

click node_android "https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/MainActivity.kt"
click node_chatui "https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/ui/chat/ChatRecommendationScreen.kt"
click node_chatrepo "https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/data/chat/DefaultChatRepository.kt"
click node_productui "https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/ui/product/ProductDetailScreen.kt"
click node_cartui "https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/ui/cart/CartScreen.kt"
click node_chatapi "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/chat.controller.ts"
click node_rag "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/rag.service.ts"
click node_rewrite "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/query-rewrite.service.ts"
click node_vectorsearch "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/vector/vector-search.service.ts"
click node_qdrant "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/vector/qdrant.client.ts"
click node_llm "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/llm/openai-compatible-chat.client.ts"
click node_imageapi "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/image-search/image-search.controller.ts"
click node_visualintent "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/image-search/visual-intent.client.ts"
click node_asr "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/asr/asr.controller.ts"
click node_products "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/products/product.service.ts"
click node_postgres "https://github.com/sheldon715/shopmate/blob/main/server/src/lib/db/pool.ts"
click node_cart "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/cart/cart.service.ts"
click node_orders "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/orders/order.service.ts"
click node_sse "https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/sse-writer.ts"

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_chatui,node_chatrepo,node_productui,node_cartui toneBlue
class node_chatapi,node_sse toneAmber
class node_rag,node_rewrite,node_vectorsearch,node_qdrant,node_llm,node_imageapi,node_visualintent,node_asr toneMint
class node_products,node_postgres,node_cart,node_orders toneRose
class node_shopper toneIndigo
```

## Components

### Android app

- [Android app entry](https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/MainActivity.kt): `client/android/app/src/main/java/com/shopmate/app/MainActivity.kt`
- [Chat and recommendations](https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/ui/chat/ChatRecommendationScreen.kt): `client/android/app/src/main/java/com/shopmate/app/ui/chat/ChatRecommendationScreen.kt`
- [Chat data client](https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/data/chat/DefaultChatRepository.kt): `client/android/app/src/main/java/com/shopmate/app/data/chat/DefaultChatRepository.kt`
- [Product details](https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/ui/product/ProductDetailScreen.kt): `client/android/app/src/main/java/com/shopmate/app/ui/product/ProductDetailScreen.kt`
- [Cart and checkout UI](https://github.com/sheldon715/shopmate/blob/main/client/android/app/src/main/java/com/shopmate/app/ui/cart/CartScreen.kt): `client/android/app/src/main/java/com/shopmate/app/ui/cart/CartScreen.kt`

### Backend API

- [Chat API](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/chat.controller.ts): `server/src/modules/chat/chat.controller.ts`
- [SSE response writer](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/sse-writer.ts): `server/src/modules/chat/sse-writer.ts`

### Discovery services

- [RAG orchestration](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/rag.service.ts): `server/src/modules/chat/rag.service.ts`
- [Query rewriting](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/chat/query-rewrite.service.ts): `server/src/modules/chat/query-rewrite.service.ts`
- [Vector retrieval](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/vector/vector-search.service.ts): `server/src/modules/vector/vector-search.service.ts`
- [Qdrant index](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/vector/qdrant.client.ts): `server/src/modules/vector/qdrant.client.ts`
- [LLM providers](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/llm/openai-compatible-chat.client.ts): `server/src/modules/llm/openai-compatible-chat.client.ts`
- [Image search API](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/image-search/image-search.controller.ts): `server/src/modules/image-search/image-search.controller.ts`
- [Visual interpretation](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/image-search/visual-intent.client.ts): `server/src/modules/image-search/visual-intent.client.ts`
- [Speech transcription](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/asr/asr.controller.ts): `server/src/modules/asr/asr.controller.ts`

### Commerce and data

- [Product catalog API](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/products/product.service.ts): `server/src/modules/products/product.service.ts`
- [PostgreSQL facts](https://github.com/sheldon715/shopmate/blob/main/server/src/lib/db/pool.ts): `server/src/lib/db/pool.ts`
- [Cart operations](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/cart/cart.service.ts): `server/src/modules/cart/cart.service.ts`
- [Checkout and orders](https://github.com/sheldon715/shopmate/blob/main/server/src/modules/orders/order.service.ts): `server/src/modules/orders/order.service.ts`

### Other components

- **Shopper**

## Connections

- Shopper → Android app entry: uses
- Android app entry → Chat and recommendations: opens chat
- Chat and recommendations → Chat data client: submits request
- Chat data client → Chat API: calls API
- Chat API → RAG orchestration: runs RAG
- RAG orchestration → Query rewriting: rewrites query
- RAG orchestration → Vector retrieval: retrieves products
- Vector retrieval → Qdrant index: searches vectors
- RAG orchestration → Product catalog API: loads product facts
- Product catalog API → PostgreSQL facts: reads catalog
- RAG orchestration → LLM providers: generates response
- Chat API → SSE response writer: streams events
- SSE response writer → Chat data client: streams response
- Chat and recommendations → Product details: opens product
- Chat and recommendations → Cart operations: requests cart action
- Cart and checkout UI → Cart operations: manages cart
- Cart operations → PostgreSQL facts: reads and writes
- Cart and checkout UI → Checkout and orders: starts checkout
- Checkout and orders → PostgreSQL facts: reads and writes
- Shopper → Image search API: provides image
- Image search API → Visual interpretation: interprets image
- Shopper → Speech transcription: provides speech