# ruc-nlpir/flashrag architecture

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

- Interactive diagram: https://gitdiagram.com/ruc-nlpir/flashrag
- Repository: https://github.com/ruc-nlpir/flashrag

## Overview

##### Core Project Type and Purpose
- FlashRAG is designed to facilitate the reproduction of RAG research and the development of new retrieval-augmented generation pipelines.
- Its purpose is to provide ready-made components (retrievers, generators, refiners, evaluators, and pipelines) as well as a UI that makes experimenting with various state-of-the-art RAG methods easier.

##### Break Down the Project’s Main Components
A. Core Library (located in the “flashrag” package):
- Config: Manages configuration files and parameters (flashrag/config/).
- Dataset: Manages loading and processing of datasets (flashrag/dataset/).
- Evaluator: Contains evaluation routines and metrics for verifying results (flashrag/evaluator/).
- Generator: Includes various generator implementations (encoder-decoder, decoder-only, and accelerator wrappers such as FastChat and vllm) (flashrag/generator/).
- Judger: Implements decision logic for whether to perform retrieval, selecting pipelines, etc. (flashrag/judger/).
- Pipeline: Orchestrates the RAG process; there are multiple pipelines (Sequential, Branching, Conditional, Loop, etc.) (flashrag/pipeline/).
- Prompt: Manages prompt template definitions (flashrag/prompt/).
- Refiner: Provides modules for refining or compressing inputs (flashrag/refiner/).
- Retriever: Implements dense retrieval methods (using faiss) and sparse retrieval methods (using BM25 with Pyserini or bm25s) (flashrag/retriever/).
- Utils: Contains helper functions, constants, and shared utilities (flashrag/utils/).
- Versioning: Version information and package metadata (flashrag/version.py).

B. Supporting and Auxiliary Layers:
- Scripts: For pre-processing, corpus chunking, and index building (scripts/ and parts of .github/scripts/).
- Examples: Example pipelines and quick-start demos (examples/).
- Documentation: Detailed guides and experiment reproducibility instructions (docs/ folder).
- WebUI: A dedicated module for an interactive visual interface, with components, pipelines, and supporting config (webui/).

C. External Dependencies & Configuration:
- Configuration and build scripts (setup.py, pyproject.toml, requirements.txt, and CI/CD files under .github/).
- External libraries: Faiss for dense indices, Pyserini or bm25s for BM25 indexing, Sentence Transformers, vllm, FastChat, and others.
- Pre-built datasets and processed indexes (as mentioned in the README under the “Supporting Datasets & Document Corpus”).

##### Component Relationships and Data Flows
- Scripts process raw document data (e.g., wiki processors in docs/original_docs/ and scripts folder).
- The retriever module builds the index using Faiss (for dense) or BM25 (for sparse).
- The “Core RAG Pipeline” section should be broken out into:
- Retrieval: The retriever modules obtain relevant documents.
- (Optional) Judging: Decision-making module decides if additional retrieval is needed.
- Generation: The generator modules produce responses based on the retrieved documents; this can include incorporating refined or compressed input via the refiner.
- Post-processing/Evaluation: The evaluator and metric calculation modules review the outputs.
- Finally, include the “User Interface Layer”:

##### Architectural Patterns and Technologies
- Modular Design: Each functionality is separated into different packages (retriever, generator, etc.) allowing flexible composition.
- Pipeline-oriented: Different pipelines (Sequential, Conditional, Loop, etc.) indicate a design that supports multiple data flow paths and conditional branching.
- Integration of third-party libraries: Faiss, Pyserini, vllm, FastChat, and Sentence Transformers are key external tools that expedite development and performance.
- CI/CD Setup: The existence of GitHub Actions workflows and related scripts indicates automated testing/build and deployment processes.

- Configuration handling and how the pipelines load settings from files (flashrag/config/basic_config.yaml) or programmatically via the Config class.
- The experimental scripts and examples, which show how a user might run experiments, building upon the pipelines.
- “FlashRAG-UI” not only as a separate module but also showing its interconnection with the pipelines (how user interaction triggers pipeline runs and displays evaluation metrics).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Stage
    RawInput["Raw Input (Query & Document Corpus)"]:::input

    %% Preprocessing/Indexing Stage
    subgraph "Preprocessing/Indexing Layer"
        Preprocess["Data Preprocessing & Indexing"]
        Scripts["Scripts"]:::support
        Documentation["Documentation"]:::support
    end

    %% Core Library
    subgraph "Core Library"
        Retriever["Retriever\n(Dense with Faiss / Sparse with BM25)"]:::core
        Judger["Judger\n(Decision Logic)"]:::core
        Pipeline["Pipeline Orchestrator"]:::core
        Generator["Generator\n(Various LLM Implementations)"]:::core
        Refiner["Refiner\n(Input Refinement/Compression)"]:::core
        Evaluator["Evaluator\n(Metrics & Outcome Evaluation)"]:::core
        
        %% Supporting utilities in Core
        Config["Config"]:::core
        Dataset["Dataset"]:::core
        Prompt["Prompt"]:::core
        Utils["Utils"]:::core
        Versioning["Versioning"]:::core
    end

    %% UI Layer
    WebUI["WebUI (Interactive Interface)"]:::ui

    %% External Dependencies
    External["External Libraries\n(Faiss, Pyserini, vllm, FastChat,\nSentence Transformers, etc.)"]:::external

    %% Flow Connections
    RawInput -->|"raw_query"| Preprocess
    Preprocess -->|"run_indexing"| Scripts
    Preprocess -->|"reference_docs"| Documentation
    Scripts -->|"build_index"| Retriever

    %% Integration from External Dependencies
    External -->|"dense/sparse index"| Retriever
    External -->|"LLM support"| Generator
    External -->|"input compression"| Refiner

    %% Core RAG Pipeline Flow
    Retriever -->|"evaluate_docs"| Judger
    Retriever -->|"pass_docs"| Pipeline
    Judger -->|"pipeline_decision"| Pipeline
    Pipeline -->|"initiate_generation"| Generator
    Pipeline -->|"initiate_refinement"| Refiner
    Generator -->|"generated_output"| Evaluator
    Refiner -->|"refined_input"| Generator
    Evaluator -->|"evaluate"| WebUI
    WebUI -->|"trigger_pipeline"| Pipeline

    %% Core Utility Dependencies (dashed links)
    Config -.->|"load_config"| Pipeline
    Dataset -.->|"data_source"| Pipeline
    Prompt -.->|"prompt_templates"| Generator
    Utils -.->|"shared_functions"| Pipeline
    Versioning -.->|"version_info"| Pipeline

    %% Supporting & Auxiliary Modules Flow
    Examples["Examples"]:::support
    Examples ---|"demo_runs"| Pipeline

    %% Click Events
    click Config "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/config/"
    click Dataset "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/dataset/"
    click Evaluator "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/evaluator/"
    click Generator "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/generator/"
    click Judger "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/judger/"
    click Pipeline "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/pipeline/"
    click Prompt "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/prompt/"
    click Refiner "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/refiner/"
    click Retriever "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/retriever/"
    click Utils "https://github.com/ruc-nlpir/flashrag/tree/main/flashrag/utils/"
    click Versioning "https://github.com/ruc-nlpir/flashrag/blob/main/flashrag/version.py"
    click Scripts "https://github.com/ruc-nlpir/flashrag/tree/main/scripts/"
    click Examples "https://github.com/ruc-nlpir/flashrag/tree/main/examples/"
    click Documentation "https://github.com/ruc-nlpir/flashrag/tree/main/docs/"
    click WebUI "https://github.com/ruc-nlpir/flashrag/tree/main/webui/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef support fill:#A9DFBF,stroke:#145A32,color:#145A32;
    classDef ui fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef input fill:#F5CBA7,stroke:#AF601A,color:#7E5109;
    classDef external fill:#D2B4DE,stroke:#6C3483,color:#4A235A;
```
