# vietdocmemory/vietnamese-rag-system architecture

> Architecture diagram of the GitHub repository vietdocmemory/vietnamese-rag-system, 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/vietdocmemory/vietnamese-rag-system
- Repository: https://github.com/vietdocmemory/vietnamese-rag-system

## Overview

Vietnamese RAG serves document-grounded question answering: a user uploads a PDF, waits for processing, then asks a question and receives streamed text with source chunks. The documented flow includes Vietnamese-aware structural chunking, hybrid dense/sparse retrieval, reranking and diversity filtering, and context-limited generation. The API coordinates these stages; Redis caching and upload status support the workflow. The README also describes a separate evaluation and root-cause-analysis capability. Some router and evaluation internals were not sampled, so links are limited to documented or evidenced ownership.

Main entry points: [`src/api/routers/chat.py`](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/api/routers/chat.py) (Chat routes), [`src/api/routers/document.py`](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/api/routers/document.py) (Document routes), [`src/ingestion/vector_store.py`](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/ingestion/vector_store.py) (Vector management), [`src/evaluation/evaluator.py`](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/evaluation/evaluator.py) (Evaluation pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_streamlit["Streamlit UI<br/>[streamlit_app.py]"]
end

subgraph group_api["API orchestration"]
  node_api_main["FastAPI app<br/>[main.py]"]
  node_document_router["Document routes<br/>[document.py]"]
  node_chat_router["Chat routes<br/>[chat.py]"]
  node_cache["Cache and status<br/>[cache.py]"]
  node_redis[("Redis")]
end

subgraph group_ingest["Document ingestion"]
  node_pdf["PDF chunking<br/>[pdf_loader.py]"]
  node_vector_manager["Vector management<br/>[vector_store.py]"]
  node_qdrant[("Qdrant")]
end

subgraph group_qa["Question answering"]
  node_retriever["Hybrid retrieval<br/>[search_engine.py]"]
  node_models["Embedding model<br/>[model_manager.py]"]
  node_generator["Answer generation<br/>[generator.py]"]
  node_ollama["Ollama LLM"]
end

subgraph group_eval["Evaluation"]
  node_evaluation["Evaluation pipeline<br/>[evaluator.py]"]
  node_judge["LLM judge"]
  node_report["Evaluation reports<br/>[evaluator.py]"]
end

node_user(("Document user"))

node_user -->|"uploads and asks"| node_streamlit
node_streamlit -->|"uploads and polls"| node_document_router
node_streamlit -->|"sends questions"| node_chat_router
node_api_main -->|"registers routes"| node_document_router
node_api_main -->|"registers routes"| node_chat_router
node_document_router -->|"processes PDF"| node_pdf
node_document_router -->|"stores chunks"| node_vector_manager
node_pdf -->|"provides chunks"| node_vector_manager
node_vector_manager -->|"encodes chunks"| node_models
node_vector_manager -->|"upserts vectors"| node_qdrant
node_document_router -->|"updates status"| node_cache
node_vector_manager -->|"searches vectors"| node_qdrant
node_chat_router -->|"checks and saves"| node_cache
node_cache -->|"reads and writes"| node_redis
node_chat_router -->|"searches query"| node_retriever
node_retriever -->|"hybrid searches"| node_qdrant
node_retriever -->|"embeds and filters"| node_models
node_chat_router -->|"generates answer"| node_generator
node_generator -->|"streams prompt"| node_ollama
node_evaluation -->|"queries API"| node_chat_router
node_evaluation -.->|"grades answers"| node_judge
node_evaluation -->|"writes metrics"| node_report

click node_streamlit "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/ui/streamlit_app.py"
click node_api_main "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/api/main.py"
click node_document_router "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/api/routers/document.py"
click node_chat_router "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/api/routers/chat.py"
click node_pdf "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/ingestion/pdf_loader.py"
click node_vector_manager "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/ingestion/vector_store.py"
click node_retriever "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/retrieval/search_engine.py"
click node_models "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/core/model_manager.py"
click node_generator "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/generation/generator.py"
click node_cache "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/core/cache.py"
click node_evaluation "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/evaluation/evaluator.py"
click node_report "https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/evaluation/evaluator.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_streamlit,node_user toneBlue
class node_api_main,node_document_router,node_chat_router,node_cache,node_redis toneAmber
class node_pdf,node_vector_manager,node_qdrant toneMint
class node_retriever,node_models,node_generator,node_ollama toneRose
class node_evaluation,node_judge,node_report toneIndigo
```

## Components

### User interfaces

- [Streamlit UI](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/ui/streamlit_app.py): `src/ui/streamlit_app.py`

### API orchestration

- [FastAPI app](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/api/main.py): `src/api/main.py`
- [Document routes](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/api/routers/document.py): `src/api/routers/document.py`
- [Chat routes](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/api/routers/chat.py): `src/api/routers/chat.py`
- [Cache and status](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/core/cache.py): `src/core/cache.py`
- **Redis**

### Document ingestion

- [PDF chunking](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/ingestion/pdf_loader.py): `src/ingestion/pdf_loader.py`
- [Vector management](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/ingestion/vector_store.py): `src/ingestion/vector_store.py`
- **Qdrant**

### Question answering

- [Hybrid retrieval](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/retrieval/search_engine.py): `src/retrieval/search_engine.py`
- [Embedding model](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/core/model_manager.py): `src/core/model_manager.py`
- [Answer generation](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/generation/generator.py): `src/generation/generator.py`
- **Ollama LLM**

### Evaluation

- [Evaluation pipeline](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/evaluation/evaluator.py): `src/evaluation/evaluator.py`
- **LLM judge**
- [Evaluation reports](https://github.com/vietdocmemory/vietnamese-rag-system/blob/main/src/evaluation/evaluator.py): `src/evaluation/evaluator.py`

### Other components

- **Document user**

## Connections

- Document user → Streamlit UI: uploads and asks
- Streamlit UI → Document routes: uploads and polls
- Streamlit UI → Chat routes: sends questions
- FastAPI app → Document routes: registers routes
- FastAPI app → Chat routes: registers routes
- Document routes → PDF chunking: processes PDF
- Document routes → Vector management: stores chunks
- PDF chunking → Vector management: provides chunks
- Vector management → Embedding model: encodes chunks
- Vector management → Qdrant: upserts vectors
- Document routes → Cache and status: updates status
- Vector management → Qdrant: searches vectors
- Chat routes → Cache and status: checks and saves
- Cache and status → Redis: reads and writes
- Chat routes → Hybrid retrieval: searches query
- Hybrid retrieval → Qdrant: hybrid searches
- Hybrid retrieval → Embedding model: embeds and filters
- Chat routes → Answer generation: generates answer
- Answer generation → Ollama LLM: streams prompt
- Evaluation pipeline → Chat routes: queries API
- Evaluation pipeline → LLM judge: grades answers
- Evaluation pipeline → Evaluation reports: writes metrics