# bo2874/chatbot_phone architecture

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

- Interactive diagram: https://gitdiagram.com/bo2874/chatbot_phone
- Repository: https://github.com/bo2874/chatbot_phone

## Overview

##### Project type and purpose
- This is a full-stack Retrieval-Augmented Generation (RAG) chatbot application (“Chatbot Phone”).
- Frontend: Streamlit UI for user interaction.
- Backend: FastAPI service implementing a modular RAG pipeline.
- Datastores: Milvus (vector DB) + PostgreSQL (relational DB).
- External service: OpenAI LLM API via LangChain.

##### File structure
- Top-level:
- app/ – backend code (FastAPI application, RAG modules, data preprocessing/indexing, config, logging).
- web/ – Streamlit frontend (web/app.py).
- requirements.txt, .env.example – dependencies and environment variables.
- app/ modules:
- main.py – entry point (creates FastAPI app, mounts router).
- router.py – defines REST endpoints (e.g., POST /query).
- chatbot.py – orchestrates RAG flow.
- rewrite_query.py – rewrites user queries using chat history.
- vector_search.py, embed.py, milvus_connection.py – semantic search pipeline.
- conn_postgres.py – SQL search interface.
- indexer.py, insert_text.py, insert_product_from_text.py, data_preprocessing.py – ETL / indexing utilities.
- logging_config.py – central logging setup.
- web/app.py: Streamlit UI that calls backend’s /query endpoint.

##### README for architecture insights
- Features: hybrid search (semantic + BM25), SQL filtering, streaming LLM tokens.
- Tech stack: Streamlit, FastAPI, LangChain, Milvus, PostgreSQL, OpenAI API.
- Deployment hints: Docker for Milvus & Postgres, uvicorn for backend, streamlit run for frontend.

##### Main components
a. Client / Frontend
- Streamlit UI (browser)
b. API Layer (FastAPI)
- Endpoint `/query`
- Query Router & Rewriter
- RAG Orchestrator (chatbot.py)
c. Retrieval Layer
- Semantic Search:
- embed.py → Milvus SDK → Milvus vector store
- Keyword / SQL Search:
- conn_postgres.py → PostgreSQL
d. LLM Layer
- LangChain orchestration → OpenAI API
- Streaming response back to API Layer
e. Data & Indexing
- ETL / Indexer modules (data_preprocessing, indexer, insert_text, insert_product)
- Config & Logging
f. Databases (external systems)
- Milvus (vector DB)
- PostgreSQL (relational DB)
g. External Service
- OpenAI LLM API

##### Relationships and data flow
1. User query enters Streamlit UI → HTTP POST `/query` → FastAPI
2. FastAPI `/query` endpoint calls rewrite_query → router → selects retriever
3. Two parallel retrieval paths:
- Semantic path: embed user query → Milvus search → top‐k vectors
- SQL path: translate filters → PostgreSQL query
4. Combine retrieval results → LangChain prompt template
5. Call OpenAI API (streaming) → receive tokens → stream back through FastAPI → Streamlit
6. ETL / Indexing modules run separately (offline jobs) to load and preprocess data into Milvus/Postgres

##### Architectural patterns & design principles
- Modular RAG pipeline: clear separation of query rewriting, retrieval, LLM generation
- Hybrid search design: vector DB + relational DB coexist
- API-driven backend: single FastAPI service exposing REST endpoints
- Streaming architecture for LLM responses (low latency)
- Decoupled frontend (Streamlit) and backend (FastAPI) for flexibility

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Frontend Layer"
        UI["Streamlit UI"]:::frontend
    end

    subgraph "API Layer"
        M["FastAPI Entry Point"]:::backend
        Rtr["API Router\nPOST /query"]:::backend
        Rewrite["Query Rewriter"]:::backend
        Orch["RAG Orchestrator"]:::backend
    end

    subgraph "Retrieval Layer"
        subgraph "Semantic Search"
            Emb["Embedding Module"]:::backend
            MilConn["Milvus Connection"]:::backend
            VecSearch["Vector Search Logic"]:::backend
        end
        SQL["Keyword/SQL Search\n(PostgreSQL)"]:::backend
    end

    subgraph "LLM Layer"
        LC["LangChain Orchestrator"]:::backend
    end

    subgraph "Data & Indexing"
        DP["Data Preprocessing"]:::etl
        IDX["Indexer Core"]:::etl
        ITXT["Insert Raw Text"]:::etl
        IPROD["Insert Product from Text"]:::etl
        CFG["Config Templates"]:::config
        LOG["Logging Configuration"]:::config
        DM["Dependency Manifest\n(requirements.txt)"]:::config
    end

    subgraph "Databases"
        Milvus["Milvus Vector DB"]:::db
        Postgres["PostgreSQL"]:::db
    end

    subgraph "External Services"
        OA["OpenAI LLM API"]:::external
    end

    UI -->|POST /query| M
    M -->|"route to /query"| Rtr
    Rtr -->|"rewrite"| Rewrite
    Rewrite -->|"rewritten query"| Orch
    Orch -->|"embed query"| Emb
    Emb -->|embeddings| MilConn
    MilConn -->|search vectors| VecSearch
    Orch -->|"SQL filters"| SQL
    VecSearch -->|"top-k vectors"| Orch
    SQL -->|"SQL results"| Orch
    Orch -->|"build prompt"| LC
    LC -->|"API call"| OA
    OA -->|"stream tokens"| Orch
    Orch -->|"stream response"| UI

    DP --> Milvus
    DP --> Postgres
    IDX --> Milvus
    ITXT --> Milvus
    IPROD --> Milvus

    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef backend fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef db fill:#FAD7A0,stroke:#B9770E,color:#7D6608
    classDef external fill:#D2B4DE,stroke:#6C3483,color:#4A235A
    classDef etl fill:#F5B7B1,stroke:#922B21,color:#641E16
    classDef config fill:#E8DAEF,stroke:#7D3C98,color:#512E5F

    click UI "https://github.com/bo2874/chatbot_phone/blob/main/web/app.py"
    click M "https://github.com/bo2874/chatbot_phone/blob/main/app/main.py"
    click Rtr "https://github.com/bo2874/chatbot_phone/blob/main/app/router.py"
    click Rewrite "https://github.com/bo2874/chatbot_phone/blob/main/app/rewrite_query.py"
    click Orch "https://github.com/bo2874/chatbot_phone/blob/main/app/chatbot.py"
    click Emb "https://github.com/bo2874/chatbot_phone/blob/main/app/embed.py"
    click MilConn "https://github.com/bo2874/chatbot_phone/blob/main/app/milvus_connection.py"
    click VecSearch "https://github.com/bo2874/chatbot_phone/blob/main/app/vector_search.py"
    click SQL "https://github.com/bo2874/chatbot_phone/blob/main/app/conn_postgres.py"
    click DP "https://github.com/bo2874/chatbot_phone/blob/main/app/data_preprocessing.py"
    click IDX "https://github.com/bo2874/chatbot_phone/blob/main/app/indexer.py"
    click ITXT "https://github.com/bo2874/chatbot_phone/blob/main/app/insert_text.py"
    click IPROD "https://github.com/bo2874/chatbot_phone/blob/main/app/insert_product_from_text.py"
    click CFG "https://github.com/bo2874/chatbot_phone/blob/main/app/config.example.py"
    click CFG "https://github.com/bo2874/chatbot_phone/blob/main/.env.example"
    click LOG "https://github.com/bo2874/chatbot_phone/blob/main/app/logging_config.py"
    click DM "https://github.com/bo2874/chatbot_phone/blob/main/requirements.txt"
```
