# v1629/kiet_buddy architecture

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

## Overview

KIET Buddy is a campus-information chatbot with a React chat client and FastAPI service over a Python RAG backend. A user submits a question; the client consumes streamed answer events while the backend routes the query to general, analytical, or text retrieval/generation paths. The knowledge base is built from JSON into vector and tabular indexes. The README describes capabilities such as caching, hybrid search, reranking, and faithfulness checks; some are represented within the pipeline components because their individual implementations are not fully excerpted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/App.jsx) (Chat app), [`backend/server/main.py`](https://github.com/v1629/kiet_buddy/blob/main/backend/server/main.py) (Chat API), [`backend/pipeline/orchestrator.py`](https://github.com/v1629/kiet_buddy/blob/main/backend/pipeline/orchestrator.py) (Query pipeline), [`backend/indexing/indexer.py`](https://github.com/v1629/kiet_buddy/blob/main/backend/indexing/indexer.py) (Data indexing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat client"]
  node_app["Chat app<br/>[App.jsx]"]
  node_chat_hook["Chat stream<br/>[useChat.js]"]
  node_status_hook["Status hook<br/>[useStatus.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_chat_views["Chat views<br/>[ChatMessage.jsx]"]
  node_message_list["Message list<br/>[MessageList.jsx]"]
  node_status_guard["Status guard<br/>[StatusGuard.jsx]"]
  node_sidebar["Sidebar<br/>[Sidebar.jsx]"]
end

subgraph group_service["HTTP service"]
  node_api_server["Chat API<br/>[main.py]"]
end

subgraph group_query["Query processing"]
  node_orchestrator["Query pipeline<br/>[orchestrator.py]"]
  node_retriever["Hybrid retrieval<br/>[retriever.py]"]
  node_web_search["Web fallback<br/>[web_search.py]"]
  node_generator["Answer generation<br/>[generator.py]"]
end

subgraph group_knowledge["Knowledge base"]
  node_indexer["Data indexing<br/>[indexer.py]"]
  node_store["Index storage<br/>[store.py]"]
end

node_user(("Chat user"))
node_qdrant[("Qdrant")]
node_duckdb[("DuckDB")]
node_llm["LLM service"]
node_cohere["Cohere services"]

node_user -->|"asks"| node_app
node_app -->|"uses"| node_chat_hook
node_app -->|"checks status"| node_status_hook
node_app -->|"guards view"| node_status_guard
node_app -->|"renders"| node_sidebar
node_app -->|"renders"| node_message_list
node_status_hook -->|"fetches status"| node_api_client
node_chat_hook -->|"posts and streams"| node_api_server
node_api_client -->|"calls endpoints"| node_api_server
node_message_list -->|"renders messages"| node_chat_views
node_chat_views -->|"renders details"| node_chat_views
node_api_server -->|"runs query"| node_orchestrator
node_api_server -->|"rebuilds indexes"| node_indexer
node_api_server -->|"checks index state"| node_store
node_orchestrator -->|"retrieves context"| node_retriever
node_orchestrator -->|"searches fallback"| node_web_search
node_orchestrator -->|"generates answers"| node_generator
node_indexer -->|"uses storage"| node_store
node_retriever -.->|"queries vectors"| node_qdrant
node_indexer -.->|"builds collection"| node_qdrant
node_indexer -->|"creates tables"| node_duckdb
node_generator -->|"executes SQL"| node_duckdb
node_retriever -.->|"embeds and reranks"| node_cohere
node_generator -->|"requests completions"| node_llm

click node_app "https://github.com/v1629/kiet_buddy/blob/main/frontend/src/App.jsx"
click node_chat_hook "https://github.com/v1629/kiet_buddy/blob/main/frontend/src/hooks/useChat.js"
click node_status_hook "https://github.com/v1629/kiet_buddy/blob/main/frontend/src/hooks/useStatus.js"
click node_api_client "https://github.com/v1629/kiet_buddy/blob/main/frontend/src/services/api.js"
click node_chat_views "https://github.com/v1629/kiet_buddy/blob/main/frontend/src/components/ChatMessage.jsx"
click node_message_list "https://github.com/v1629/kiet_buddy/blob/main/frontend/src/components/MessageList.jsx"
click node_status_guard "https://github.com/v1629/kiet_buddy/blob/main/frontend/src/components/StatusGuard.jsx"
click node_sidebar "https://github.com/v1629/kiet_buddy/blob/main/frontend/src/components/Sidebar.jsx"
click node_api_server "https://github.com/v1629/kiet_buddy/blob/main/backend/server/main.py"
click node_orchestrator "https://github.com/v1629/kiet_buddy/blob/main/backend/pipeline/orchestrator.py"
click node_retriever "https://github.com/v1629/kiet_buddy/blob/main/backend/retrieval/retriever.py"
click node_web_search "https://github.com/v1629/kiet_buddy/blob/main/backend/retrieval/web_search.py"
click node_generator "https://github.com/v1629/kiet_buddy/blob/main/backend/generation/generator.py"
click node_indexer "https://github.com/v1629/kiet_buddy/blob/main/backend/indexing/indexer.py"
click node_store "https://github.com/v1629/kiet_buddy/blob/main/backend/storage/store.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_app,node_chat_hook,node_status_hook,node_api_client,node_chat_views,node_message_list,node_status_guard,node_sidebar,node_user toneBlue
class node_api_server,node_qdrant,node_duckdb toneAmber
class node_orchestrator,node_retriever,node_web_search,node_generator toneMint
class node_indexer,node_store toneRose
class node_llm,node_cohere toneIndigo
```

## Components

### Chat client

- [Chat app](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat stream](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/hooks/useChat.js): `frontend/src/hooks/useChat.js`
- [Status hook](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/hooks/useStatus.js): `frontend/src/hooks/useStatus.js`
- [API client](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Chat views](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/components/ChatMessage.jsx): `frontend/src/components/ChatMessage.jsx`
- [Message list](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/components/MessageList.jsx): `frontend/src/components/MessageList.jsx`
- [Status guard](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/components/StatusGuard.jsx): `frontend/src/components/StatusGuard.jsx`
- [Sidebar](https://github.com/v1629/kiet_buddy/blob/main/frontend/src/components/Sidebar.jsx): `frontend/src/components/Sidebar.jsx`

### HTTP service

- [Chat API](https://github.com/v1629/kiet_buddy/blob/main/backend/server/main.py): `backend/server/main.py`

### Query processing

- [Query pipeline](https://github.com/v1629/kiet_buddy/blob/main/backend/pipeline/orchestrator.py): `backend/pipeline/orchestrator.py`
- [Hybrid retrieval](https://github.com/v1629/kiet_buddy/blob/main/backend/retrieval/retriever.py): `backend/retrieval/retriever.py`
- [Web fallback](https://github.com/v1629/kiet_buddy/blob/main/backend/retrieval/web_search.py): `backend/retrieval/web_search.py`
- [Answer generation](https://github.com/v1629/kiet_buddy/blob/main/backend/generation/generator.py): `backend/generation/generator.py`

### Knowledge base

- [Data indexing](https://github.com/v1629/kiet_buddy/blob/main/backend/indexing/indexer.py): `backend/indexing/indexer.py`
- [Index storage](https://github.com/v1629/kiet_buddy/blob/main/backend/storage/store.py): `backend/storage/store.py`

### Other components

- **Chat user**
- **Qdrant**
- **DuckDB**
- **LLM service**
- **Cohere services**

## Connections

- Chat user → Chat app: asks
- Chat app → Chat stream: uses (evidence: `frontend/src/App.jsx`)
- Chat app → Status hook: checks status (evidence: `frontend/src/App.jsx`)
- Chat app → Status guard: guards view (evidence: `frontend/src/App.jsx`)
- Chat app → Sidebar: renders (evidence: `frontend/src/App.jsx`)
- Chat app → Message list: renders (evidence: `frontend/src/App.jsx`)
- Status hook → API client: fetches status (evidence: `frontend/src/hooks/useStatus.js`)
- Chat stream → Chat API: posts and streams (evidence: `frontend/src/hooks/useChat.js`)
- API client → Chat API: calls endpoints (evidence: `frontend/src/services/api.js`)
- Message list → Chat views: renders messages (evidence: `frontend/src/components/MessageList.jsx`)
- Chat views → Chat views: renders details (evidence: `frontend/src/components/ChatMessage.jsx`)
- Chat API → Query pipeline: runs query (evidence: `backend/server/main.py`)
- Chat API → Data indexing: rebuilds indexes (evidence: `backend/server/main.py`)
- Chat API → Index storage: checks index state (evidence: `backend/server/main.py`)
- Query pipeline → Hybrid retrieval: retrieves context (evidence: `backend/pipeline/orchestrator.py`)
- Query pipeline → Web fallback: searches fallback (evidence: `backend/pipeline/orchestrator.py`)
- Query pipeline → Answer generation: generates answers (evidence: `backend/pipeline/orchestrator.py`)
- Data indexing → Index storage: uses storage (evidence: `backend/indexing/indexer.py`)
- Hybrid retrieval → Qdrant: queries vectors
- Data indexing → Qdrant: builds collection
- Data indexing → DuckDB: creates tables (evidence: `backend/indexing/indexer.py`)
- Answer generation → DuckDB: executes SQL (evidence: `backend/generation/generator.py`)
- Hybrid retrieval → Cohere services: embeds and reranks
- Answer generation → LLM service: requests completions (evidence: `backend/generation/generator.py`)
