# lehoanganhtai13/agentic-hcmut-chatbot architecture

> Architecture diagram of the GitHub repository lehoanganhtai13/agentic-hcmut-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lehoanganhtai13/agentic-hcmut-chatbot
- Repository: https://github.com/lehoanganhtai13/agentic-hcmut-chatbot

## Overview

##### Project Type and Purpose
- This is a full‑stack, microservices‑based chatbot system using Retrieval‑Augmented Generation (RAG) to answer admission queries for HCMUT.
- Key goals: semantic search over university documents, context‑aware chat, multilingual support, agentic reasoning.

##### File Structure
- Top‑level directories:
- chatbot/           ← core Python code
- chatbot/core/      ← retrieval, generation, model clients
- chatbot/indexing/  ← document and FAQ ingestion pipelines
- chatbot/prompts/   ← reusable prompt templates
- chatbot/server/    ← four Dockerized API microservices
- chatbot/utils/     ← database clients (Milvus, MinIO), OpenAI websocket
- chatbot/workflow/  ← CLI scripts for building index & inference
- database/          ← Docker‑compose definitions for Milvus & MinIO
- Makefile orchestrates network, volumes, containers, backup/restore.

##### README
- Confirms a four‑service architecture (chatbot_server, document_server, faq_server, index_server).
- Uses Milvus (vector DB) + MinIO (object store) for RAG.
- Relies on LLMs via OpenAI or local clients for embeddings/generation.

A. Clients
- Web/Mobile Chat UI (end user)
B. API Gateway / Chatbot Server
- chatbot/server/chatbot_server/server_app.py
- Routes user queries to retriever & generator services
C. Microservices (Docker containers on `chatbot` network)
1. Index Service
– Endpoint to ingest or re‑build the semantic index
– Invokes `chatbot/indexing/` pipelines
2. Document Service
– Serves context documents from MinIO
3. FAQ Service
– Serves FAQ entries and handles FAQ‑specific retrieval
4. Chat Service (the main conversational API)
– Coordinates:
- Retrieval → `core/retriever/*` (uses Milvus or BM25)
- Generation → `core/generator` & `core/model_clients/llm.py`
D. Datastores
- Milvus (vector embeddings)
- MinIO (raw documents, chunks, FAQ JSONs)
E. Model Clients
- Embedding service (`embedder.py`)
- LLM API (`llm.py`) or local model loaders
F. Workflow Scripts
- build_index.py → Preprocess & push embeddings/documents into Milvus & MinIO
- chatbot_inference.py → Standalone CLI chat

##### Architectural Patterns & Tech Stack
- Microservices deployed via Docker Compose on a dedicated `chatbot` network.
- RAG pipeline: ingestion (indexing) + retrieval + generation.
- Semantic search uses Milvus; object storage via MinIO.
- Prompts are externalized for easy tuning.
- Strict separation of concerns: indexing vs retrieval vs generation vs API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingestion & Workflow
    subgraph "Indexing Pipeline" 
        direction TB
        ContextPipeline["Context Document Pipeline"]:::workflow
        FAQPipeline["FAQ Ingestion Pipeline"]:::workflow
    end
    subgraph "Workflow Scripts"
        direction TB
        BuildIndex["build_index.py"]:::workflow
        InferenceCLI["chatbot_inference.py"]:::workflow
    end

    %% API Layer
    subgraph "Chatbot API Layer"
        direction TB
        ChatService["Chat Service (Chatbot API)"]:::microservice
        IndexService["Index Service API"]:::microservice
        DocumentService["Document Service API"]:::microservice
        FAQService["FAQ Service API"]:::microservice
    end

    %% Model Clients
    subgraph "Model Clients"
        direction TB
        Embedder["Embedding Client"]:::model
        LLMClient["LLM Client"]:::model
        BM25Client["BM25 Fallback"]:::model
    end

    %% Datastores
    subgraph "Datastores"
        direction TB
        MilvusDB["Milvus (Vector DB)"]:::datastore
        MinIO["MinIO (Object Store)"]:::datastore
    end

    %% External LLM
    ExternalLLM("External LLM API"):::external

    %% Prompts & Chat Store
    PromptsIndex["Indexing Prompts"]:::workflow
    PromptsQuery["Query Prompts"]:::workflow
    ChatStore["Chat Store (Session Cache)"]:::model

    %% Client
    Client["Web/Mobile Chat UI"]:::external

    %% Connections
    Client -->|"HTTP/REST"| ChatService
    ChatService -->|"ingest/reindex"| IndexService
    ChatService -->|"fetch docs"| DocumentService
    ChatService -->|"fetch faqs"| FAQService

    IndexService -->|"runs pipelines"| ContextPipeline
    IndexService -->|"runs pipelines"| FAQPipeline

    BuildIndex -->|"push embeddings"| MilvusDB
    BuildIndex -->|"store docs/faqs"| MinIO

    InferenceCLI -->|"CLI chat"| ChatService

    ChatService -->|"retrieve embeddings"| MilvusDB
    ChatService -->|"retrieve objects"| MinIO
    DocumentService -->|"reads objects"| MinIO
    FAQService -->|"reads objects"| MinIO

    ChatService -->|"embed/query"| Embedder
    ChatService -->|"call llm"| LLMClient
    ChatService -->|"bm25 fallback"| BM25Client
    LLMClient -->|"API calls"| ExternalLLM

    ChatService --> ChatStore

    PromptsIndex --- ContextPipeline
    PromptsQuery --- ChatService

    %% Click Events
    click ChatService "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/server/chatbot_server/server_app.py"
    click IndexService "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/server/index_server/server_app.py"
    click DocumentService "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/server/document_server/server_app.py"
    click FAQService "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/server/faq_server/server_app.py"
    click ContextPipeline "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/tree/main/chatbot/indexing/context_document/"
    click FAQPipeline "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/tree/main/chatbot/indexing/faq/"
    click BuildIndex "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/workflow/build_index.py"
    click InferenceCLI "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/workflow/chatbot_inference.py"
    click Embedder "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/core/model_clients/embedder.py"
    click LLMClient "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/core/model_clients/llm.py"
    click BM25Client "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/core/model_clients/bm25.py"
    click ChatStore "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/chatbot/core/chat_stores/cache_chat_store.py"
    click PromptsIndex "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/tree/main/chatbot/prompts/indexing"
    click PromptsQuery "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/tree/main/chatbot/prompts/query"
    click MilvusDB "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/database/milvus/docker-compose.yml"
    click MinIO "https://github.com/lehoanganhtai13/agentic-hcmut-chatbot/blob/main/database/minio/docker-compose.yml"

    %% Styles
    classDef microservice fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef datastore fill:#ffe082,stroke:#ff8f00,color:#e65100
    classDef workflow fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    classDef model fill:#d1c4e9,stroke:#6a1b9a,color:#4a148c
    classDef external fill:#b3e5fc,stroke:#0277bd,color:#01579b
```
