# trinhvanminh/advanced-rag architecture

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

- Interactive diagram: https://gitdiagram.com/trinhvanminh/advanced-rag
- Repository: https://github.com/trinhvanminh/advanced-rag

## Overview

##### Project Type and Purpose
- The project is a generative AI platform that leverages Retrieval-Augmented Generation (RAG) techniques. It incorporates several components such as document ingestion, prompt management, vector search/embedding, QnA functionality, and possibly reinforcement learning aspects.
- The README mentions keywords and ideas such as RAG, RILF, semantic routing, and fine-tuning. This indicates that the project is designed for advanced AI-powered querying/chatbot solutions that integrate retrieval and generation pipelines.

##### Analyzing the File Structure
- Top-Level Files and Directories:
- App files like app.py (Streamlit) and flask_app.py (Flask) define two different UI/interaction entry points.
- The "src" directory contains modules for configuration (config.py), constants, ingestion, QnA, prompts, and the core RAG functionality (rag.py).
- Utility/support modules are located in src/utils and include conversation handling.
- The "docs" directory holds research reports, architecture sketches, and pricing details indicating that the project may be in an experimental or evolving phase with ongoing research.
- Scripts and auxiliary files (preprocessing an XLSX file) indicate data pre-processing functionalities.
- Configuration and dependency management files (requirements.txt, Dockerfile, .env.example) suggest how the project is built and deployed.

##### Insights From the README
- The README is used to provide instructions to run the application with two different interfaces (Streamlit and Flask), which implies a decoupled UI mechanism.
- These clues point to a layered architecture: a user interface layer, a core processing layer for managing retrieval-augmented generation, and an ingestion/preprocessing layer.

a. Main Components:
- User Interface Layer: Represent both Streamlit (app.py) and Flask (flask_app.py) entry points.
- API/Controller Layer: A routing layer that accepts user requests and channels them to the proper processing module.
- Core Processing Modules:
- Ingestion Module: document_loader.py, src/ingestion.py, and possibly the preprocessing script.
- RAG Module: src/rag.py, which implements the retrieval-augmented generation logic.
- QnA Module: src/qna.py, handling question-answer interactions.
- Prompt Management: src/prompts.py manages templates or prompt constructions for interacting with the generative model.
- Utility/Conversation Management: Modules located within src/utils (such as conversation.py) support context management.
- Configuration Module: src/config.py and src/constants.py provide overarching settings and constants.
- Data Source/External Services: Although not explicitly mentioned, consider including vector search/embedding services (potentially cloud vector DB, embedding models) and external APIs referenced in the README links (e.g., OpenAI, AWS, or Google Vertex AI).

b. Relationships and Interactions:
- Users initiate a request through the UI layer (either via Streamlit or Flask).
- The request is sent to the controller/API that calls the ingestion process if document/data processing is needed.
- The core processing modules then leverage the RAG pipeline to retrieve relevant documents, use prompt templates, and generate responses.
- The QnA module may coordinate between retrieval results and user query context.
- Utilities manage conversation context and flow.
- Configuration and constants centralize system settings and parameters across layers.

c. Important Architectural Patterns:
- Separation of Concerns: Distinct modules for UI, processing, and utility functions.
- Modular Design: Clear division into ingestion, generation, and conversation handling.
- Config-Driven Behavior: Central configuration to alter behavior without deeply impacting code structure.
- Adaptability: Support for multiple UI frameworks (similar business logic underlying both Streamlit and Flask implementations).

d. Technologies, Frameworks, or Libraries:
- Python-based frameworks: Flask and Streamlit for UI.
- Potential Machine Learning/AI libraries for vector embedding and language generation.
- Docker configuration files indicate containerized deployment.
- Utility libraries (implied by requirements.txt) for data processing, handling XLSX files, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and UI Layer
    User["User"]:::external

    subgraph "User Interface Layer"
        ST["Streamlit UI"]:::ui
        FL["Flask UI"]:::ui
    end

    User -->|"initiates"| ST
    User -->|"initiates"| FL

    %% API/Controller Layer
    API["API/Controller"]:::processing
    ST -->|"sends request"| API
    FL -->|"sends request"| API

    %% Core Processing Layer
    subgraph "Core Processing"
        %% Ingestion Module Subgraph
        subgraph "Ingestion Module"
            DL["Document Loader"]:::processing
            ING["Ingestion Script"]:::processing
            PRE["Preprocessing Script"]:::processing
        end
        
        RAG["RAG Engine"]:::processing
        QN["QnA Module"]:::processing
        PM["Prompt Manager"]:::processing
    end

    %% Support Modules Layer
    subgraph "Support Modules"
        UTIL["Conversation Utility"]:::config
        CONF["Configuration & Constants"]:::config
    end

    %% External Services
    EXT["Vector Search/Embedding Service"]:::external

    %% Data Flow
    API -->|"routes-to"| DL
    API -->|"routes-to"| ING
    API -->|"routes-to"| PRE
    DL -->|"provides data"| RAG
    ING -->|"provides data"| RAG
    PRE -->|"provides processed data"| RAG
    API -->|"direct request"| RAG
    RAG -->|"queries"| QN
    RAG -->|"uses"| PM
    QN -->|"feedback to"| PM
    PM -->|"sends response"| API
    RAG -->|"calls"| EXT
    
    %% Support Connections (dashed for supporting roles)
    UTIL ---|"supports"| API
    CONF ---|"configures"| API
    CONF ---|"configures"| RAG
    CONF ---|"configures"| QN
    CONF ---|"configures"| PM

    %% Click Events
    click ST "https://github.com/trinhvanminh/advanced-rag/blob/main/app.py"
    click FL "https://github.com/trinhvanminh/advanced-rag/blob/main/flask_app.py"
    click DL "https://github.com/trinhvanminh/advanced-rag/blob/main/document_loader.py"
    click ING "https://github.com/trinhvanminh/advanced-rag/blob/main/src/ingestion.py"
    click PRE "https://github.com/trinhvanminh/advanced-rag/blob/main/scripts/preprocess_the_xlsx_file.py"
    click RAG "https://github.com/trinhvanminh/advanced-rag/blob/main/src/rag.py"
    click QN "https://github.com/trinhvanminh/advanced-rag/blob/main/src/qna.py"
    click PM "https://github.com/trinhvanminh/advanced-rag/blob/main/src/prompts.py"
    click CONF "https://github.com/trinhvanminh/advanced-rag/blob/main/src/config.py"
    click UTIL "https://github.com/trinhvanminh/advanced-rag/blob/main/src/utils/conversation.py"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef processing fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
