# chutungduongg/chatbot_answering_vietnamese_history architecture

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

- Interactive diagram: https://gitdiagram.com/chutungduongg/chatbot_answering_vietnamese_history
- Repository: https://github.com/chutungduongg/chatbot_answering_vietnamese_history

## Overview

Vietnamese History LLM provides a chat UI for grounded answers, with Hybrid RAG and a tool-using Central Agent as distinct inference modes. The main flow runs from a user question through the frontend and API to retrieval and model generation, then streams the response and citations back. Conversations and uploaded documents add persistent history and temporary retrieval; evaluation is a separate capability. Some runtime wiring is documented but not visible in the excerpts, so those relationships cite the README rather than implying unsampled calls.

Main entry points: [`app/tools/registry.py`](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/registry.py) (Tool registry), [`app/main.py`](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/main.py) (FastAPI assembly), [`frontend/src/services/api.js`](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/services/api.js) (API client), [`app/api/routes.py`](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/api/routes.py) (Chat routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat interface"]
  node_chat_ui["Chat UI<br/>[App.jsx]"]
  node_stream_hook["Chat streaming<br/>[useChatStream.js]"]
  node_session_hook["Conversation state<br/>[useChatSession.js]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and sessions"]
  node_api_app["FastAPI assembly<br/>[main.py]"]
  node_chat_routes["Chat routes<br/>[routes.py]"]
  node_conversation_api["Conversation API<br/>[conversations.py]"]
  node_conversation_store[("Conversation store<br/>[store.py]")]
end

subgraph group_knowledge["Retrieval and documents"]
  node_attachment_service["Attachment processing<br/>[attachments.py]"]
  node_rag_service["RAG service<br/>[rag_service.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
end

subgraph group_inference["Inference and tools"]
  node_hybrid_runtime["Hybrid runtime<br/>[hybrid_runtime.py]"]
  node_model["Qwen generation<br/>[qwen.py]"]
  node_central_runtime["Central agent<br/>[runtime.py]"]
  node_tool_registry["Tool registry<br/>[registry.py]"]
  node_history_tool["History search<br/>[local_search.py]"]
  node_attachment_tool["Attachment search"]
  node_web_tool["Web search<br/>[web_search.py]"]
  node_wiki_tool["Wikipedia tools<br/>[wikipedia.py]"]
  node_page_tool["Page fetcher<br/>[page_fetcher.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Retrieval and answer evaluation<br/>[runner.py]"]
  node_retrieval_eval["Retrieval metrics<br/>[retrieval.py]"]
end

node_user(("User"))

node_user -->|"asks"| node_chat_ui
node_chat_ui -->|"streams chat"| node_stream_hook
node_chat_ui -->|"manages sessions"| node_session_hook
node_stream_hook -->|"calls"| node_api_client
node_session_hook -->|"calls"| node_api_client
node_api_client -->|"sends chat requests"| node_chat_routes
node_api_client -->|"requests conversations"| node_conversation_api
node_api_app -->|"mounts routes"| node_chat_routes
node_api_app -->|"mounts routes"| node_conversation_api
node_chat_routes -->|"dispatches hybrid"| node_hybrid_runtime
node_chat_routes -->|"dispatches central"| node_central_runtime
node_conversation_api -->|"reads and writes"| node_conversation_store
node_api_app -->|"initializes retrieval"| node_rag_service
node_api_app -->|"initializes runtime"| node_hybrid_runtime
node_api_app -->|"initializes runtime"| node_central_runtime
node_attachment_service -->|"stores documents"| node_conversation_store
node_attachment_service -->|"uses embeddings"| node_rag_service
node_rag_service -->|"provides shared retriever"| node_retrieval
node_hybrid_runtime -->|"retrieves context"| node_retrieval
node_hybrid_runtime -->|"generates answer"| node_model
node_central_runtime -->|"generates answer"| node_model
node_central_runtime -->|"dispatches tools"| node_tool_registry
node_api_app -->|"registers tools"| node_tool_registry
node_tool_registry -->|"registers"| node_history_tool
node_tool_registry -->|"registers"| node_attachment_tool
node_tool_registry -->|"registers"| node_web_tool
node_tool_registry -->|"registers"| node_wiki_tool
node_tool_registry -->|"registers"| node_page_tool
node_history_tool -->|"searches history"| node_retrieval
node_attachment_tool -->|"searches uploads"| node_attachment_service
node_evaluation -->|"scores retrieval"| node_retrieval_eval

click node_chat_ui "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/App.jsx"
click node_stream_hook "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/hooks/useChatStream.js"
click node_session_hook "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/hooks/useChatSession.js"
click node_api_client "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/services/api.js"
click node_api_app "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/main.py"
click node_chat_routes "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/api/routes.py"
click node_conversation_api "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/api/conversations.py"
click node_conversation_store "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/chat/store.py"
click node_attachment_service "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/chat/attachments.py"
click node_rag_service "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/services/rag_service.py"
click node_retrieval "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/rag/retrieval.py"
click node_hybrid_runtime "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/rag/hybrid_runtime.py"
click node_model "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/models/qwen.py"
click node_central_runtime "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/central/runtime.py"
click node_tool_registry "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/registry.py"
click node_history_tool "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/local_search.py"
click node_attachment_tool "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/attachment_search.py"
click node_web_tool "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/web_search.py"
click node_wiki_tool "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/wikipedia.py"
click node_page_tool "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/page_fetcher.py"
click node_evaluation "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/evaluation/runner.py"
click node_retrieval_eval "https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/evaluation/metrics/retrieval.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_chat_ui,node_stream_hook,node_session_hook,node_api_client,node_user toneBlue
class node_api_app,node_chat_routes,node_conversation_api,node_conversation_store toneAmber
class node_attachment_service,node_rag_service,node_retrieval toneMint
class node_hybrid_runtime,node_model,node_central_runtime,node_tool_registry,node_history_tool,node_attachment_tool,node_web_tool,node_wiki_tool,node_page_tool toneRose
class node_evaluation,node_retrieval_eval toneIndigo
```

## Components

### Chat interface

- [Chat UI](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat streaming](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/hooks/useChatStream.js): `frontend/src/hooks/useChatStream.js`
- [Conversation state](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/hooks/useChatSession.js): `frontend/src/hooks/useChatSession.js`
- [API client](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and sessions

- [FastAPI assembly](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/main.py): `app/main.py`
- [Chat routes](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/api/routes.py): `app/api/routes.py`
- [Conversation API](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/api/conversations.py): `app/api/conversations.py`
- [Conversation store](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/chat/store.py): `app/chat/store.py`

### Retrieval and documents

- [Attachment processing](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/chat/attachments.py): `app/chat/attachments.py`
- [RAG service](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/services/rag_service.py): `app/services/rag_service.py`
- [Hybrid retrieval](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/rag/retrieval.py): `app/rag/retrieval.py`

### Inference and tools

- [Hybrid runtime](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/rag/hybrid_runtime.py): `app/rag/hybrid_runtime.py`
- [Qwen generation](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/models/qwen.py): `app/models/qwen.py`
- [Central agent](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/central/runtime.py): `app/central/runtime.py`
- [Tool registry](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/registry.py): `app/tools/registry.py`
- [History search](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/local_search.py): `app/tools/local_search.py`
- [Attachment search](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/attachment_search.py): `app/tools/attachment_search.py`
- [Web search](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/web_search.py): `app/tools/web_search.py`
- [Wikipedia tools](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/wikipedia.py): `app/tools/wikipedia.py`
- [Page fetcher](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/app/tools/page_fetcher.py): `app/tools/page_fetcher.py`

### Evaluation

- [Retrieval and answer evaluation](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/evaluation/runner.py): `evaluation/runner.py`
- [Retrieval metrics](https://github.com/chutungduongg/chatbot_answering_vietnamese_history/blob/main/evaluation/metrics/retrieval.py): `evaluation/metrics/retrieval.py`

### Other components

- **User**

## Connections

- User → Chat UI: asks
- Chat UI → Chat streaming: streams chat (evidence: `frontend/src/App.jsx`)
- Chat UI → Conversation state: manages sessions (evidence: `frontend/src/App.jsx`)
- Chat streaming → API client: calls (evidence: `frontend/src/hooks/useChatStream.js`)
- Conversation state → API client: calls (evidence: `frontend/src/hooks/useChatSession.js`)
- API client → Chat routes: sends chat requests
- API client → Conversation API: requests conversations
- FastAPI assembly → Chat routes: mounts routes (evidence: `app/main.py`)
- FastAPI assembly → Conversation API: mounts routes (evidence: `app/main.py`)
- Chat routes → Hybrid runtime: dispatches hybrid
- Chat routes → Central agent: dispatches central
- Conversation API → Conversation store: reads and writes (evidence: `app/api/conversations.py`)
- FastAPI assembly → RAG service: initializes retrieval (evidence: `app/main.py`)
- FastAPI assembly → Hybrid runtime: initializes runtime (evidence: `app/main.py`)
- FastAPI assembly → Central agent: initializes runtime (evidence: `app/main.py`)
- Attachment processing → Conversation store: stores documents (evidence: `app/chat/attachments.py`)
- Attachment processing → RAG service: uses embeddings (evidence: `app/chat/attachments.py`)
- RAG service → Hybrid retrieval: provides shared retriever (evidence: `app/rag/retrieval.py`)
- Hybrid runtime → Hybrid retrieval: retrieves context
- Hybrid runtime → Qwen generation: generates answer
- Central agent → Qwen generation: generates answer
- Central agent → Tool registry: dispatches tools (evidence: `app/central/runtime.py`)
- FastAPI assembly → Tool registry: registers tools (evidence: `app/main.py`)
- Tool registry → History search: registers (evidence: `app/main.py`)
- Tool registry → Attachment search: registers (evidence: `app/main.py`)
- Tool registry → Web search: registers (evidence: `app/main.py`)
- Tool registry → Wikipedia tools: registers (evidence: `app/main.py`)
- Tool registry → Page fetcher: registers (evidence: `app/main.py`)
- History search → Hybrid retrieval: searches history (evidence: `app/tools/local_search.py`)
- Attachment search → Attachment processing: searches uploads (evidence: `app/tools/attachment_search.py`)
- Retrieval and answer evaluation → Retrieval metrics: scores retrieval