# huangl22/chat3gpp architecture

> Architecture diagram of the GitHub repository huangl22/chat3gpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huangl22/chat3gpp
- Repository: https://github.com/huangl22/chat3gpp

## Overview

##### Project type and purpose
- Chat3GPP is a Retrieval-Augmented Generation (RAG) framework specialized for 3GPP technical documents.
- It provides both an offline data‐ingestion pipeline (preprocessing and indexing into Elasticsearch) and an online query/response engine (user chat clients, retrievers, reranker, LLM).

##### File structure
- Top-level scripts:
- init_database.py – builds and populates Elasticsearch
- chat.py – simple direct chat client using LLM
- kb_chat.py – chat client that augments responses with retrieved 3GPP content
- Directories:
- configs/ – configuration of knowledge-base and model parameters
– kb_configs.py (Elasticsearch index settings, retrieval hyperparameters)
– model_configs.py (paths or endpoints for your embedding and LLM models)
- preprocess/ – data-cleaning scripts (remove_content.py)
- text_splitter/ – document chunking utilities (TSdocx_splitter.py)
- retrievers/ – retrieval abstractions and implementations
– base.py (abstract retriever interface)
– VectorRetriever.py (vector‐based Elasticsearch query)
- server/ – core RAG pipeline modules
– embedding.py (query/document embedding)
– reranker.py (reorder top-k retrievals)
– llm.py (invokes the language model for generation)
- utils.py – shared helper functions

##### README for insights
- Clearly describes two phases:
a) Preprocess & import standard docs into Elasticsearch
b) Run either chat.py or kb_chat.py for inference
- Dependencies: Python 3.8, Elasticsearch, ML models (via HuggingFace/OpenAI)

##### Main components
a. Offline Data-Ingestion Pipeline
- Preprocessor Module (preprocess/remove_content.py)
- Text Splitter Module (text_splitter/TSdocx_splitter.py)
- Database Initializer (init_database.py)
- Elasticsearch Cluster (knowledge base)
b. Online Inference Pipeline
- Chat Clients (chat.py, kb_chat.py)
- RAG Server Modules (server/embedding.py, server/llm.py, server/reranker.py)
- Retriever Layer (retrievers/base.py, retrievers/VectorRetriever.py)
- Model Serving (embedding model, generation LLM)
- Elasticsearch for retrieval

##### Relationships and interactions
- Offline:
1. Raw 3GPP docs → Preprocessor → Cleaned text
2. Cleaned text → Text Splitter → Chunks
3. init_database reads chunks + configs → indexes into Elasticsearch
- Online (kb_chat.py flow):
1. User Query → embedding.py → vector representation
2. VectorRetriever → Elasticsearch → top-N relevant chunks
3. reranker.py → reorder chunks by relevance
4. llm.py → prompt LLM with query + top contexts → Generated Response
5. Response → returned to User
- Direct Chat (chat.py) bypasses retrieval & reranker; sends query to llm.py only

##### Architectural patterns & design principles
- Modular pipeline: clear separation of preprocessing, indexing, retrieval, ranking, and generation
- Config-driven: all model and database settings in configs/
- Interface abstraction: retrievers implement a common interface (base.py) for future extension
- RAG pattern: blend vector search + LLM generation

##### Relevant technologies/frameworks
- Elasticsearch (vector and text search)
- Python 3.8, standard libraries
- HuggingFace Transformers or OpenAI API for embeddings & generation
- Optional: Docker/Kubernetes for Elasticsearch deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration
    subgraph "Configuration" 
        direction TB
        ConfigKB["Knowledge-Base & Retrieval Hyperparams"]:::config
        ConfigModel["Embedding & LLM Model Settings"]:::config
        Utils["Shared Utilities (utils.py)"]:::config
    end

    %% Offline Indexing Pipeline
    subgraph "Offline Indexing" 
        direction TB
        RawDocs["Raw 3GPP Documents"]:::offline
        Preprocessor["Preprocessor Module"]:::offline
        TextSplitter["Text Splitter Module"]:::offline
        DBInit["Database Initializer"]:::offline
        ES["Elasticsearch Cluster"]:::external
    end

    RawDocs -->|"clean"| Preprocessor
    Preprocessor -->|"chunks"| TextSplitter
    TextSplitter -->|"data + configs"| DBInit
    DBInit -->|"index"| ES

    ConfigKB --> DBInit
    ConfigKB --> TextSplitter
    Utils -.-> Preprocessor
    Utils -.-> TextSplitter
    Utils -.-> DBInit

    %% Online Inference Pipeline
    subgraph "Online Inference" 
        direction TB
        User["User"]:::online
        Chat["Direct Chat Client (chat.py)"]:::online
        KBChat["KB Chat Client (kb_chat.py)"]:::online
        Embed["Embedding Service"]:::online
        BaseRet["Abstract Retriever Interface"]:::online
        Retriever["Vector Retriever"]:::online
        Reranker["Reranker Service"]:::online
        LLM["LLM Invocation Service"]:::online
        ModelAPI["LLM Model API"]:::external
    end

    User --> Chat
    Chat -->|"query"| LLM
    LLM -->|"generate"| ModelAPI
    ModelAPI -->|"response"| Chat

    User --> KBChat
    KBChat -->|"embed(query)"| Embed
    Embed -->|"vector"| Retriever
    Retriever -->|"search(vectors)"| ES
    ES -->|"top-N chunks"| Reranker
    Reranker -->|"reranked contexts"| LLM
    LLM -->|"generate(prompt)"| ModelAPI
    ModelAPI -->|"response"| KBChat

    BaseRet -.-> Retriever

    ConfigModel --> Embed
    ConfigModel --> LLM
    ConfigKB --> Retriever
    Utils -.-> Embed
    Utils -.-> Reranker
    Utils -.-> LLM

    %% Click Events
    click Preprocessor "https://github.com/huangl22/chat3gpp/blob/master/preprocess/remove_content.py"
    click TextSplitter "https://github.com/huangl22/chat3gpp/blob/master/text_splitter/TSdocx_splitter.py"
    click DBInit "https://github.com/huangl22/chat3gpp/blob/master/init_database.py"
    click Chat "https://github.com/huangl22/chat3gpp/blob/master/chat.py"
    click KBChat "https://github.com/huangl22/chat3gpp/blob/master/kb_chat.py"
    click BaseRet "https://github.com/huangl22/chat3gpp/blob/master/retrievers/base.py"
    click Retriever "https://github.com/huangl22/chat3gpp/blob/master/retrievers/VectorRetriever.py"
    click Embed "https://github.com/huangl22/chat3gpp/blob/master/server/embedding.py"
    click Reranker "https://github.com/huangl22/chat3gpp/blob/master/server/reranker.py"
    click LLM "https://github.com/huangl22/chat3gpp/blob/master/server/llm.py"
    click ConfigKB "https://github.com/huangl22/chat3gpp/blob/master/configs/kb_configs.py"
    click ConfigModel "https://github.com/huangl22/chat3gpp/blob/master/configs/model_configs.py"
    click Utils "https://github.com/huangl22/chat3gpp/blob/master/utils.py"

    %% Styles
    classDef offline fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef online fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef config fill:#f8d7da,stroke-dasharray: 5 5,stroke:#333,stroke-width:1px
```
