# szu-zy/ragflow architecture

> Architecture diagram of the GitHub repository szu-zy/ragflow, 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/szu-zy/ragflow
- Repository: https://github.com/szu-zy/ragflow

## Overview

##### Project Overview & Purpose
- RAGFlow is an open‐source Retrieval-Augmented Generation (RAG) engine that leverages deep document understanding.
- It orchestrates a multi-model workflow—integrating LLMs with document parsers, embedding models, and retrieval engines—to generate grounded, cited answers from a wide variety of source formats.

##### Major Components
a. Frontend (Web)
– Located in the “web” folder, this is the complete React-based (TypeScript) frontend that handles user interactions, presentation of chat interfaces, knowledge graphs, file management, and dashboards.
b. Backend / API
– The “api” directory is a core component providing REST or HTTP API endpoints. It incorporates multiple “apps” (e.g., canvas, conversation, document, file, knowledge-base, llm, and user modules) interfacing with the database and external services.
– The “api/db” subdirectories manage multiple database models and service utilities (e.g., tasks, user, and session management).
c. Agent and Agentic Reasoning
– Under “agent” you find numerous components (e.g., canvas, agent/component with dedicated agents for integrations like baidu, bing, google, etc.).
– “agentic_reasoning” supports additional reasoning patterns like deep research and prompt management.
d. Document Parsing (DeepDoc)
– The “deepdoc” directory contains parsers for various file formats (docx, excel, pdf, markdown, images, etc.) and vision modules (OCR, layout recognition).
e. RAG and Retrieval Modules
– The “rag” folder organizes modules for handling retrieval (e.g., retrieval, QA, and knowledge graph extraction), interactions with external storage systems (Elasticsearch/Infinity), and integration with LLM models.
f. Supporting Modules
– “graphrag” provides utilities for graph-based data processing (e.g., entity resolution, graph extraction) which likely support knowledge graph features.
– “sdk” provides libraries and examples (Python client and modules) for external integrations with RAGFlow’s API.
g. Deployment Infrastructure
– Dockerfiles, Helm charts, and “docker” folder show how the system is containerized and deployed.
– Configuration files (in conf, docker/.env, service_conf.yaml) illustrate environment-dependent settings and service orchestration.
h. Integrations and Extensions
– The “intergrations” directory contains example integrations for chat applications (e.g., ChatGPT-on-WeChat, Chrome extension) that extend RAGFlow’s capabilities into different platforms.

##### Relationships & Data Flow
- The web frontend communicates with the API backend through REST endpoints (and possibly WebSocket connections for live chat functionalities).
- The API layer, organized into multiple “apps” and “db” services, acts as a bridge between frontend requests and the underlying processing modules (agent, deepdoc, and rag).
- The Agent components manage dynamic workflows: using a DSL to compose various agent operations (like retrieval, generation, rewriting, and keyword extraction).
- The DeepDoc module parses complex documents—producing data that is used by the RAG component to generate context-aware answers.
- The RAG module orchestrates retrieval (from Elasticsearch or Infinity), applies embedding and re-ranking models, and returns curated answers.
- The SDK and integration plugins give outside clients (or browser extensions) controlled access to these services.

##### Architectural Patterns & Technologies
- Modular Service Composition: Each major component (frontend, API, agent, deepdoc, rag) is separated logically allowing independent development and deployment.
- Microservice/MVC Style: The “api” directory is organized into submodules (“apps”, “db”, “utils”), indicating separation of concerns similar to MVC.
- Containerization: Use of Docker and Helm illustrates cloud-native deployment and scaling practices.
- Template-Based Workflows: With many JSON templates in the “agent/templates” directory, the design embraces template-driven reproducibility for different RAG patterns.

- Be detailed: Make sure each component and connection is clearly represented.
- Separate concerns: Differentiate between presentation (frontend), service orchestration (API and agent), data processing (DeepDoc, RAG), and persistence (database/Elasticsearch/Infinity).
- By including notes on purpose (e.g., “Agent Component – handles dynamic workflows and integrations”, “DeepDoc – document parsing for structured data extraction”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        User["User"]:::frontend
        Frontend["Web Frontend"]:::frontend
        User -->|"access"| Frontend
    end

    %% API Layer
    subgraph "API Layer"
        APIServer["API Server"]:::backend
        Database[(Database/Storage)]:::infra
        Frontend -->|"REST_api"| APIServer
        APIServer -->|"query_DB"| Database
    end

    %% Processing Layer
    subgraph "Processing Layer"
        AgentEngine["Agent Engine"]:::processing
        Agentic["Agentic Reasoning"]:::processing
        DeepDoc["DeepDoc Parser"]:::processing
        RAG["RAG Orchestrator"]:::processing
        APIServer -->|"invoke"| AgentEngine
        APIServer -->|"invoke"| Agentic
        APIServer -->|"document_data"| DeepDoc
        APIServer -->|"generate_answer"| RAG
        AgentEngine -->|"workflow"| RAG
        Agentic -->|"workflow"| RAG
        DeepDoc -->|"parsed_data"| RAG
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        GraphUtil["Graph Utilities"]:::processing
        PythonSDK["Python SDK"]:::processing
        APIServer -->|"graph_queries"| GraphUtil
        PythonSDK -->|"API_integration"| APIServer
    end

    %% Integrations and Extensions
    subgraph "Integrations"
        Integrations["Integrations & Extensions"]:::backend
        Integrations -->|"API_access"| APIServer
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        Docker["Docker"]:::infra
        Helm["Helm"]:::infra
        Config["Config Files"]:::infra
        Docker -->|"deploy"| APIServer
        Helm -->|"deploy"| APIServer
        Config -->|"deploy"| APIServer
        Docker -->|"deploy"| Frontend
    end

    %% Click Events
    click Frontend "https://github.com/szu-zy/ragflow/tree/main/web/"
    click APIServer "https://github.com/szu-zy/ragflow/tree/main/api/"
    click AgentEngine "https://github.com/szu-zy/ragflow/tree/main/agent/"
    click Agentic "https://github.com/szu-zy/ragflow/tree/main/agentic_reasoning/"
    click DeepDoc "https://github.com/szu-zy/ragflow/tree/main/deepdoc/"
    click RAG "https://github.com/szu-zy/ragflow/tree/main/rag/"
    click GraphUtil "https://github.com/szu-zy/ragflow/tree/main/graphrag/"
    click PythonSDK "https://github.com/szu-zy/ragflow/tree/main/sdk/python/"
    click Docker "https://github.com/szu-zy/ragflow/tree/main/docker/"
    click Helm "https://github.com/szu-zy/ragflow/tree/main/helm/"
    click Config "https://github.com/szu-zy/ragflow/tree/main/conf/"
    click Integrations "https://github.com/szu-zy/ragflow/tree/main/intergrations/"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef processing fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
