# lynkvu2901/rag-bank-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/lynkvu2901/rag-bank-chatbot
- Repository: https://github.com/lynkvu2901/rag-bank-chatbot

## Overview

This is a Vietnamese Vietcombank FAQ RAG chatbot. A user submits a question in the Streamlit interface; generation applies privacy and investment guardrails, retrieves and reranks FAQ evidence, rejects low-similarity matches, then asks Claude to draft an answer with cited sources. The repository also includes FAQ scraping and chunk/index preparation, plus retrieval and generation evaluation. The README documents these capabilities; some underlying modules and generated processed files are absent from the supplied tree, so their wiring is shown only where documentation supports it.

Main entry points: [`src/generation.py`](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/generation.py) (Answer generation), [`src/hybrid_search.py`](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/hybrid_search.py) (Hybrid retrieval), [`src/evaluate.py`](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/evaluate.py) (Pipeline evaluation), [`app.py`](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/app.py) (Streamlit chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_ui["Streamlit chat<br/>[app.py]"]
end

subgraph group_rag["Answer pipeline"]
  node_guardrails["Input guardrails<br/>[generation.py]"]
  node_hybrid["Hybrid retrieval<br/>[hybrid_search.py]"]
  node_retrieval["Vector retrieval<br/>[retrieval.py]"]
  node_reranker["Cross-encoder rerank<br/>[reranking.py]"]
  node_threshold["Similarity filter<br/>[generation.py]"]
  node_generation["Answer generation<br/>[generation.py]"]
end

subgraph group_knowledge["FAQ knowledge"]
  node_scraper["FAQ scraper<br/>[scrape_vcb_faq.py]"]
  node_rawfaq["Raw FAQ data<br/>[vcb_faq.json]"]
  node_chunking["FAQ chunking<br/>[chunking.py]"]
  node_embedding["Embedding encoder<br/>[embedding.py]"]
  node_vectorstore[("FAISS index<br/>[vector_store.py]")]
end

subgraph group_quality["Evaluation"]
  node_evaluation["Pipeline evaluation<br/>[evaluate.py]"]
end

node_customer(("Questioner"))
node_claude["Claude API"]
node_vcb["VCB FAQ site"]

node_customer -->|"asks"| node_ui
node_ui -->|"calls answer"| node_generation
node_generation -->|"checks input"| node_guardrails
node_generation -->|"retrieves candidates"| node_hybrid
node_hybrid -->|"uses index"| node_retrieval
node_retrieval -->|"loads index"| node_vectorstore
node_hybrid -->|"reranks candidates"| node_reranker
node_generation -->|"checks score"| node_threshold
node_generation -->|"requests completion"| node_claude
node_claude -->|"returns answer"| node_generation
node_generation -->|"returns answer and sources"| node_ui
node_vcb -.->|"provides FAQ"| node_scraper
node_scraper -.->|"writes FAQ data"| node_rawfaq
node_rawfaq -->|"supplies FAQs"| node_chunking
node_chunking -->|"supplies chunks"| node_embedding
node_embedding -->|"builds vectors"| node_vectorstore
node_evaluation -->|"measures retrieval"| node_hybrid
node_evaluation -->|"evaluates answers"| node_generation
node_evaluation -.->|"uses judge"| node_claude

click node_ui "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/app.py"
click node_guardrails "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/generation.py"
click node_hybrid "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/hybrid_search.py"
click node_retrieval "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/retrieval.py"
click node_reranker "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/reranking.py"
click node_threshold "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/generation.py"
click node_generation "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/generation.py"
click node_scraper "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/scrape_vcb_faq.py"
click node_rawfaq "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/data/raw/vcb_faq.json"
click node_chunking "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/chunking.py"
click node_embedding "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/embedding.py"
click node_vectorstore "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/vector_store.py"
click node_evaluation "https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/evaluate.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_ui toneBlue
class node_guardrails,node_hybrid,node_retrieval,node_reranker,node_threshold,node_generation toneAmber
class node_scraper,node_rawfaq,node_chunking,node_embedding,node_vectorstore,node_claude toneMint
class node_evaluation toneRose
class node_customer,node_vcb toneIndigo
```

## Components

### Chat experience

- [Streamlit chat](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/app.py): `app.py`

### Answer pipeline

- [Input guardrails](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/generation.py): `src/generation.py`
- [Hybrid retrieval](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/hybrid_search.py): `src/hybrid_search.py`
- [Vector retrieval](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/retrieval.py): `src/retrieval.py`
- [Cross-encoder rerank](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/reranking.py): `src/reranking.py`
- [Similarity filter](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/generation.py): `src/generation.py`
- [Answer generation](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/generation.py): `src/generation.py`

### FAQ knowledge

- [FAQ scraper](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/scrape_vcb_faq.py): `scrape_vcb_faq.py`
- [Raw FAQ data](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/data/raw/vcb_faq.json): `data/raw/vcb_faq.json`
- [FAQ chunking](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/chunking.py): `src/chunking.py`
- [Embedding encoder](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/embedding.py): `src/embedding.py`
- [FAISS index](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/vector_store.py): `src/vector_store.py`

### Evaluation

- [Pipeline evaluation](https://github.com/lynkvu2901/rag-bank-chatbot/blob/main/src/evaluate.py): `src/evaluate.py`

### Other components

- **Questioner**
- **Claude API**
- **VCB FAQ site**

## Connections

- Questioner → Streamlit chat: asks
- Streamlit chat → Answer generation: calls answer
- Answer generation → Input guardrails: checks input
- Answer generation → Hybrid retrieval: retrieves candidates
- Hybrid retrieval → Vector retrieval: uses index
- Vector retrieval → FAISS index: loads index
- Hybrid retrieval → Cross-encoder rerank: reranks candidates
- Answer generation → Similarity filter: checks score
- Answer generation → Claude API: requests completion
- Claude API → Answer generation: returns answer
- Answer generation → Streamlit chat: returns answer and sources
- VCB FAQ site → FAQ scraper: provides FAQ
- FAQ scraper → Raw FAQ data: writes FAQ data
- Raw FAQ data → FAQ chunking: supplies FAQs
- FAQ chunking → Embedding encoder: supplies chunks
- Embedding encoder → FAISS index: builds vectors
- Pipeline evaluation → Hybrid retrieval: measures retrieval
- Pipeline evaluation → Answer generation: evaluates answers
- Pipeline evaluation → Claude API: uses judge