# iiiiiiiinseong/langgraph_rag_agent architecture

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

- Interactive diagram: https://gitdiagram.com/iiiiiiiinseong/langgraph_rag_agent
- Repository: https://github.com/iiiiiiiinseong/langgraph_rag_agent

## Overview

##### Project type and purpose
- This is a full-stack AI chatbot system specialized for personalized financial advice.
- It implements an Adaptive Self-Retrieval-Augmented-Generation (Self-RAG) pipeline on top of a Flask web server (with Gradio UI), backed by document preprocessing, hybrid search (BM25 + vector), ChromaDB embedding store, and OpenAI’s GPT-4o-mini for answer generation and self-evaluation.

##### File structure
- Top-level directories:
- db_preprocessing: raw CSV → Python scripts → cleaned data
- flask_server: Flask app (app.py, routes.py, config.py), static PDF store, Jinja2 templates
- src: core RAG pipeline scripts (adaptive_self_rag.py, entity_extraction.py, qd_mapping.py, evaluate_retrieval.py)
- results: evaluation JSON/CSV outputs

##### README for additional insights
- Describes the Adaptive Self-RAG chain built using LangChain & LangGraph
- Highlights hybrid search (bm25 + vector via HuggingFace Embeddings + ChromaDB)
- Shows roles of question routing, document retrieval, answer generation, hallucination check, and personalization

##### Main components
a. Data Preparation
- Raw CSV files (db_preprocessing/rawdata)
- Data processing scripts → cleaned data
b. Document Store & Indexing
- Static PDF folder (flask_server/static/pdf_storage) – raw documents
- ChromaDB (vector index) + BM25 index (hybrid search engine)
c. Adaptive Self-RAG Pipeline
- Question Router (classifies financial vs. general)
- Parallel document retrievers (deposit, fixed, loan, savings)
- Relevance evaluator (self-assessment of retrieved docs)
- Self-corrector (re-formulates queries if needed)
- Generator (GPT-4o-mini) → draft answer
- Answer Evaluator (checks hallucination, relevance)
d. Web Server & UI
- Flask server routes → calls pipeline
- Gradio interface embedded in Flask templates
e. Evaluation & Metrics
- Q-D mapping modules (qd_mapping.py, qd_mapping_multi.py)
- evaluate_retrieval.py → produces JSON/CSV in results/

##### Relationships and interactions
- User → Flask/Gradio UI → HTTP POST “ask” → Pipeline entry
- Pipeline → Query Router → (if general → direct GPT call; if financial → RAG chain)
- RAG chain → Hybrid Search → ChromaDB + bm25 → filtered docs → Generator
- Generated answer → Self-evaluation & possible re-query → Final answer
- All data flows (documents, embeddings, queries, answers) mediated by pipeline modules
- Evaluation scripts operate offline on results directory

##### Architectural patterns and design principles
- Modular pipeline orchestrated by LangGraph → clearly separated stages
- Hybrid design: retrieval (vector + BM25) + generative model
- Self-feedback loop: generator → evaluator → optional re-query
- Separation of concerns: data prep, document store, pipeline logic, web server, evaluation

##### Technologies and frameworks to annotate
- Python 3.x, Flask, Jinja2, Gradio
- LangChain & LangGraph for RAG orchestration
- OpenAI GPT-4o-mini (LLM)
- HuggingFace Embeddings, ChromaDB, rank-BM25
- CSV / JSON for Q-D mapping, evaluation outputs

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User & Web Server"
        User["User (Browser)"]:::external
        FlaskApp["Flask App"]:::web
        Config["Config"]:::web
        Routes["Routes"]:::web
        Utils["Utils"]:::web
        subgraph "Templates"
            Index["index.html"]:::web
            Category["category.html"]:::web
            SearchResults["search_results.html"]:::web
        end
    end

    subgraph "Data Preparation"
        RawCSV["Raw CSV Files"]:::datastore
        DP1["data_processing_demand.py"]:::datastore
        DP2["data_processing_fixed.py"]:::datastore
        DP3["data_processing_loan.py"]:::datastore
        DP4["data_processing_saving.py"]:::datastore
    end

    subgraph "Document Store & Indexing"
        PDFRepo["PDF Storage"]:::datastore
        HybridIndex["Hybrid Index & Embedding Store"]:::datastore
        EntityExtract["Entity Extraction"]:::pipeline
    end

    subgraph "Adaptive Self-RAG Pipeline"
        Router["Question Router"]:::pipeline
        Retrievers["Parallel Document Retrievers"]:::pipeline
        Generator["Answer Generator"]:::pipeline
        RelevanceEval["Relevance Evaluator"]:::pipeline
        SelfCorrector["Self-Corrector"]:::pipeline
        AnswerEval["Answer Evaluator"]:::eval
    end

    subgraph "Evaluation & Metrics"
        QD1["qd_mapping.py"]:::eval
        QD2["qd_mapping_multi.py"]:::eval
        EvalScript["evaluate_retrieval.py"]:::eval
        EvalOutputs["Results Outputs"]:::datastore
    end

    subgraph "Diagram Source"
        DiagSrc["adaptive_self_rag_memory.mmd"]:::datastore
    end

    User -->|"HTTP POST ask"| Routes
    Routes -->|calls| Router
    Router -->|"general question"| Generator
    Router -->|"financial question"| Retrievers
    Retrievers -->|"retrieved docs"| Generator
    Generator -->|"draft answer"| RelevanceEval
    RelevanceEval -->|"feedback"| SelfCorrector
    SelfCorrector -->|"reformulated query"| Retrievers
    Generator -->|"LLM response"| AnswerEval
    AnswerEval -->|"final answer"| Routes
    Routes -->|render| Index
    Routes -->|render| Category
    Routes -->|render| SearchResults

    RawCSV --> DP1
    RawCSV --> DP2
    RawCSV --> DP3
    RawCSV --> DP4

    PDFRepo --> Retrievers
    HybridIndex --> Retrievers
    EntityExtract --> Retrievers

    QD1 -->|generate mapping| EvalOutputs
    QD2 -->|generate mapping| EvalOutputs
    EvalScript -->|produce metrics| EvalOutputs

    click RawCSV "https://github.com/iiiiiiiinseong/langgraph_rag_agent/tree/main/db_preprocessing/rawdata"
    click DP1 "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/db_preprocessing/data_processing_demand.py"
    click DP2 "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/db_preprocessing/data_processing_fixed.py"
    click DP3 "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/db_preprocessing/data_processing_loan.py"
    click DP4 "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/db_preprocessing/data_processing_saving.py"
    click PDFRepo "https://github.com/iiiiiiiinseong/langgraph_rag_agent/tree/main/flask_server/static/pdf_storage"
    click HybridIndex "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/adaptive_self_rag.py"
    click Router "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/adaptive_self_rag.py"
    click Retrievers "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/adaptive_self_rag.py"
    click EntityExtract "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/entity_extraction.py"
    click RelevanceEval "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/evaluate_retrieval.py"
    click SelfCorrector "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/adaptive_self_rag.py"
    click Generator "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/adaptive_self_rag.py"
    click AnswerEval "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/evaluate_retrieval.py"
    click FlaskApp "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/flask_server/app.py"
    click Config "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/flask_server/config.py"
    click Routes "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/flask_server/routes.py"
    click Utils "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/flask_server/utils.py"
    click Index "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/flask_server/templates/index.html"
    click Category "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/flask_server/templates/category.html"
    click SearchResults "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/flask_server/templates/search_results.html"
    click QD1 "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/qd_mapping.py"
    click QD2 "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/qd_mapping_multi.py"
    click EvalScript "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/evaluate_retrieval.py"
    click EvalOutputs "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/results/summary.csv"
    click DiagSrc "https://github.com/iiiiiiiinseong/langgraph_rag_agent/blob/main/src/adaptive_self_rag_memory.mmd"

    classDef datastore fill:#a2caff,stroke:#000
    classDef pipeline fill:#a2ffa2,stroke:#000
    classDef web fill:#ffcc80,stroke:#000
    classDef eval fill:#d3d3d3,stroke:#000
    classDef external fill:#ffffff,stroke:#000
```
