# hoangsyviet04/rag_ecommerce_b2c architecture

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

- Interactive diagram: https://gitdiagram.com/hoangsyviet04/rag_ecommerce_b2c
- Repository: https://github.com/hoangsyviet04/rag_ecommerce_b2c

## Overview

This is a Vietnamese B2C e-commerce sales assistant: the frontend submits a chat request, the API delegates to a chat service, and the intent router selects policy retrieval, product lookup, chitchat, or human handoff. The service loads short-term conversation context, applies response guardrails, and the API schedules SQL chat-history persistence. Separate product capabilities include SQL-to-vector synchronization, document ingestion, and RAG evaluation. Edges follow shown calls or README descriptions; unsampled subsystems are included only where documented.

Main entry points: [`src/api/routes.py`](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/api/routes.py) (API routes), [`src/engine/retriever.py`](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/retriever.py) (Hybrid retriever), [`src/services/chat_service.py`](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/services/chat_service.py) (Chat service), [`src/engine/router.py`](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/router.py) (Intent router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interface"]
  node_frontend["Chat frontend<br/>[index.html]"]
  node_api["FastAPI app<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
end

subgraph group_chat["Chat orchestration"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_intent_router["Intent router<br/>[router.py]"]
  node_generator["LLM generator<br/>[generator.py]"]
  node_guardrails["Output guardrails<br/>[guardrails.py]"]
  node_memory["Chat memory<br/>[memory.py]"]
  node_redis[("Redis cache")]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
  node_vector_access["Vector DB access<br/>[vector_db.py]"]
  node_chroma[("ChromaDB")]
  node_bm25[("BM25 index<br/>[bm25_index.pkl]")]
  node_ingestion["Document ingestion"]
  node_raw_docs["Policy documents"]
end

subgraph group_commerce["Commerce data"]
  node_sql_history[("SQL chat history<br/>[init.sql]")]
  node_product_tools["Product tools<br/>[product_tools.py]"]
  node_sql_access["SQL access<br/>[relational_db.py]"]
  node_sql_server[("SQL Server<br/>[init.sql]")]
  node_sync["Product sync<br/>[sync_handler.py]"]
end

subgraph group_operations["Operations"]
  node_evaluation["RAG evaluation<br/>[evaluation.py]"]
  node_tracing["LangSmith tracing"]
end

node_customer(("Customer"))
node_langsmith["LangSmith"]

node_customer -->|"asks"| node_frontend
node_frontend -->|"submits chat"| node_api
node_api -->|"mounts routes"| node_routes
node_routes -->|"processes chat"| node_chat_service
node_chat_service -->|"reads/writes context"| node_redis
node_chat_service -->|"routes query"| node_intent_router
node_intent_router -->|"generates replies"| node_generator
node_intent_router -->|"retrieves policy"| node_retriever
node_intent_router -->|"dispatches tools"| node_product_tools
node_chat_service -->|"filters reply"| node_guardrails
node_routes -->|"saves history"| node_memory
node_memory -->|"writes messages"| node_sql_access
node_sql_access -->|"connects"| node_sql_server
node_routes -->|"inserts products"| node_sql_access
node_product_tools -->|"queries products"| node_sql_access
node_product_tools -->|"semantic search"| node_retriever
node_retriever -->|"uses vector search"| node_vector_access
node_vector_access -->|"searches vectors"| node_chroma
node_retriever -->|"loads keyword index"| node_bm25
node_raw_docs -->|"supplies documents"| node_ingestion
node_ingestion -->|"writes embeddings"| node_chroma
node_ingestion -->|"writes index"| node_bm25
node_routes -->|"schedules sync"| node_sync
node_sync -->|"reads products"| node_sql_server
node_sync -->|"upserts/deletes products"| node_chroma
node_api -->|"enables tracing"| node_tracing
node_tracing -.->|"traces runs"| node_langsmith
node_evaluation -.->|"evaluates retrieval"| node_retriever
node_evaluation -.->|"evaluates answers"| node_generator

click node_frontend "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/frontend/index.html"
click node_api "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/api/main.py"
click node_routes "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/api/routes.py"
click node_chat_service "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/services/chat_service.py"
click node_intent_router "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/router.py"
click node_generator "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/generator.py"
click node_guardrails "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/guardrails.py"
click node_memory "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/memory.py"
click node_sql_history "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/data/init.sql"
click node_product_tools "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/tools/product_tools.py"
click node_sql_access "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/database/relational_db.py"
click node_sql_server "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/data/init.sql"
click node_sync "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/processing/sync_handler.py"
click node_retriever "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/retriever.py"
click node_vector_access "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/database/vector_db.py"
click node_chroma "https://github.com/hoangsyviet04/rag_ecommerce_b2c/tree/main/data/chroma_db"
click node_bm25 "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/data/bm25_index.pkl"
click node_ingestion "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/processing/langchain_ingestion.py"
click node_raw_docs "https://github.com/hoangsyviet04/rag_ecommerce_b2c/tree/main/data/raw"
click node_evaluation "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/utils/evaluation.py"
click node_tracing "https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/monitoring/langsmith_tracer.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_frontend,node_api,node_routes toneBlue
class node_chat_service,node_intent_router,node_generator,node_guardrails,node_memory,node_redis toneAmber
class node_retriever,node_vector_access,node_chroma,node_bm25,node_ingestion,node_raw_docs toneMint
class node_sql_history,node_product_tools,node_sql_access,node_sql_server,node_sync toneRose
class node_evaluation,node_tracing,node_customer,node_langsmith toneIndigo
```

## Components

### User interface

- [Chat frontend](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/frontend/index.html): `frontend/index.html`
- [FastAPI app](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/api/main.py): `src/api/main.py`
- [API routes](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/api/routes.py): `src/api/routes.py`

### Chat orchestration

- [Chat service](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/services/chat_service.py): `src/services/chat_service.py`
- [Intent router](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/router.py): `src/engine/router.py`
- [LLM generator](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/generator.py): `src/engine/generator.py`
- [Output guardrails](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/guardrails.py): `src/engine/guardrails.py`
- [Chat memory](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/memory.py): `src/engine/memory.py`
- **Redis cache**

### Knowledge and retrieval

- [Hybrid retriever](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/engine/retriever.py): `src/engine/retriever.py`
- [Vector DB access](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/database/vector_db.py): `src/database/vector_db.py`
- [ChromaDB](https://github.com/hoangsyviet04/rag_ecommerce_b2c/tree/main/data/chroma_db): `data/chroma_db`
- [BM25 index](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/data/bm25_index.pkl): `data/bm25_index.pkl`
- [Document ingestion](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/processing/langchain_ingestion.py): `src/processing/langchain_ingestion.py`
- [Policy documents](https://github.com/hoangsyviet04/rag_ecommerce_b2c/tree/main/data/raw): `data/raw`

### Commerce data

- [SQL chat history](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/data/init.sql): `data/init.sql`
- [Product tools](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/tools/product_tools.py): `src/tools/product_tools.py`
- [SQL access](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/database/relational_db.py): `src/database/relational_db.py`
- [SQL Server](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/data/init.sql): `data/init.sql`
- [Product sync](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/processing/sync_handler.py): `src/processing/sync_handler.py`

### Operations

- [RAG evaluation](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/src/utils/evaluation.py): `src/utils/evaluation.py`
- [LangSmith tracing](https://github.com/hoangsyviet04/rag_ecommerce_b2c/blob/main/monitoring/langsmith_tracer.py): `monitoring/langsmith_tracer.py`

### Other components

- **Customer**
- **LangSmith**

## Connections

- Customer → Chat frontend: asks (evidence: `README.md`)
- Chat frontend → FastAPI app: submits chat (evidence: `README.md`)
- FastAPI app → API routes: mounts routes (evidence: `src/api/main.py`)
- API routes → Chat service: processes chat (evidence: `src/api/routes.py`)
- Chat service → Redis cache: reads/writes context (evidence: `src/services/chat_service.py`)
- Chat service → Intent router: routes query (evidence: `src/services/chat_service.py`)
- Intent router → LLM generator: generates replies (evidence: `src/engine/router.py`)
- Intent router → Hybrid retriever: retrieves policy (evidence: `src/engine/router.py`)
- Intent router → Product tools: dispatches tools (evidence: `src/engine/router.py`)
- Chat service → Output guardrails: filters reply (evidence: `src/services/chat_service.py`)
- API routes → Chat memory: saves history (evidence: `src/api/routes.py`)
- Chat memory → SQL access: writes messages (evidence: `src/engine/memory.py`)
- SQL access → SQL Server: connects (evidence: `src/database/relational_db.py`)
- API routes → SQL access: inserts products (evidence: `src/api/routes.py`)
- Product tools → SQL access: queries products (evidence: `src/tools/product_tools.py`)
- Product tools → Hybrid retriever: semantic search (evidence: `src/tools/product_tools.py`)
- Hybrid retriever → Vector DB access: uses vector search (evidence: `src/engine/retriever.py`)
- Vector DB access → ChromaDB: searches vectors (evidence: `src/database/vector_db.py`)
- Hybrid retriever → BM25 index: loads keyword index
- Policy documents → Document ingestion: supplies documents (evidence: `src/processing/langchain_ingestion.py`)
- Document ingestion → ChromaDB: writes embeddings (evidence: `src/processing/langchain_ingestion.py`)
- Document ingestion → BM25 index: writes index (evidence: `src/processing/langchain_ingestion.py`)
- API routes → Product sync: schedules sync (evidence: `src/api/routes.py`)
- Product sync → SQL Server: reads products (evidence: `src/processing/sync_handler.py`)
- Product sync → ChromaDB: upserts/deletes products (evidence: `src/processing/sync_handler.py`)
- FastAPI app → LangSmith tracing: enables tracing (evidence: `src/api/main.py`)
- LangSmith tracing → LangSmith: traces runs (evidence: `monitoring/langsmith_tracer.py`)
- RAG evaluation → Hybrid retriever: evaluates retrieval (evidence: `README.md`)
- RAG evaluation → LLM generator: evaluates answers (evidence: `README.md`)
