# kevin-khoamai/ragflow architecture

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

- Interactive diagram: https://gitdiagram.com/kevin-khoamai/ragflow
- Repository: https://github.com/kevin-khoamai/ragflow

## Overview

##### Project Type and Purpose
- This is RAGFlow, an open-source, full-stack Retrieval-Augmented Generation (RAG) engine.
- Purpose: provide a complete RAG workflow that ingests heterogeneous documents, extracts and indexes chunks (“DeepDoc”), performs retrieval + re-ranking, runs LLM-based generation, and exposes APIs + UI for business integration.

##### High-Level Architectural Domains
- Frontend (web/)
- React + TypeScript UI for dataset management, chat/flow editors, agents, document viewers.
- Communicates over HTTP/REST with the backend API.
- Backend API Layer (api/)
- FastAPI/Uvicorn apps: each “app” module under api/apps handles a domain (chat, dataset, file, document, kb, llm, auth, plugin, etc.).
- API gateway/ragflow_server.py routes requests to these applications.
- Exposes SDK (sdk/python/ragflow_sdk) and HTTP OpenAPI.
- Core RAG Engine (rag/, deepdoc/, agent/, agentic_reasoning/)
- rag/: orchestrates retrieval, chunking, embedding search, LLM calls, re-ranking.
- deepdoc/: document parsers (pdf, docx, ppt, excel, html, markdown, etc.) + vision OCR/layout.
- agent/: modular “Agent” components (search, code, email, iterate, template) with DSL builder (canvas.py + component/).
- agentic_reasoning/: deep research workflows, multi-step prompts.
- Sandbox Executor (sandbox/)
- gVisor-backed container manager for code execution.
- HTTP service for running untrusted code in isolated environments.
- Plugins and Integrations (plugin/, intergrations/)
- Plugin manager embeds LLM-tool plugins, Chrome extension, ChatGPT-WeChat bridge.
- Data Stores and External Services (docker/, helm/)
- Relational DB: MySQL (api/db/db_models.py).
- Object storage: MinIO for raw docs.
- Search engine: Elasticsearch or Infinity (vector + full-text).
- Cache: Redis.
- LLM & embedding endpoints: OpenAI/Azure/HuggingFace/Tavily, etc.
- Additional: Langfuse, MCP server for multi-tenant.

##### Essential Elements to Capture
- Labels: component names, technologies, ports (optional).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients & SDK" 
        direction TB
        Browser["Web Browser"]:::client
        CLI["CLI"]:::client
        SDK["Python SDK"]:::client
    end

    click Browser "https://github.com/kevin-khoamai/ragflow/tree/main/web/"
    click SDK "https://github.com/kevin-khoamai/ragflow/tree/main/sdk/python/ragflow_sdk/"

    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        ReactApp["React App (web/src)"]:::frontend
        Nginx["nginx (serves UI)"]:::frontend
    end

    click ReactApp "https://github.com/kevin-khoamai/ragflow/tree/main/web/"

    %% API Gateway & Microservices Layer
    subgraph "Backend API Layer" 
        direction TB
        APIGateway["API Gateway\n(ragflow_server.py)"]:::api
        subgraph "FastAPI Apps" 
            direction TB
            ChatApp["Chat Service"]:::api
            DatasetApp["Dataset Service"]:::api
            FileApp["File Service"]:::api
            DocumentApp["Document Service"]:::api
            KBApp["KB Service"]:::api
            LLMApp["LLM Service"]:::api
            PluginApp["Plugin Service"]:::api
            AuthApp["Auth Service"]:::api
        end
        Settings["api/settings.py"]:::api
        Constants["api/constants.py"]:::api
        Utils["api/utils/"]:::api
    end

    click APIGateway "https://github.com/kevin-khoamai/ragflow/blob/main/api/ragflow_server.py"
    click ChatApp "https://github.com/kevin-khoamai/ragflow/tree/main/api/apps/"
    click DatasetApp "https://github.com/kevin-khoamai/ragflow/tree/main/api/apps/"
    click FileApp "https://github.com/kevin-khoamai/ragflow/tree/main/api/apps/"
    click DocumentApp "https://github.com/kevin-khoamai/ragflow/tree/main/api/apps/"
    click KBApp "https://github.com/kevin-khoamai/ragflow/tree/main/api/apps/"
    click LLMApp "https://github.com/kevin-khoamai/ragflow/tree/main/api/apps/"
    click PluginApp "https://github.com/kevin-khoamai/ragflow/tree/main/api/apps/"
    click AuthApp "https://github.com/kevin-khoamai/ragflow/tree/main/api/apps/"
    click Settings "https://github.com/kevin-khoamai/ragflow/blob/main/api/settings.py"
    click Constants "https://github.com/kevin-khoamai/ragflow/blob/main/api/constants.py"
    click Utils "https://github.com/kevin-khoamai/ragflow/tree/main/api/utils/"

    %% Core Engines Layer
    subgraph "Core Engines" 
        direction TB
        RAGOrch["RAG Orchestrator\n(rag/)"]:::core
        subgraph "Retrieval & LLM Modules"
            direction TB
            LLMLib["LLM Models (rag/llm/)"]:::core
            NLP["Retrieval Modules (rag/nlp/)"]:::core
        end
        DeepDoc["DeepDoc Parsers\n(deepdoc/)"]:::core
        AgentDSL["Agent DSL Engine\n(agent/)"]:::core
        AgentReason["Agentic Reasoning\n(agentic_reasoning/)"]:::core
        SandboxExec["Sandbox Executor\n(sandbox/executor_manager/)"]:::core
    end

    click RAGOrch "https://github.com/kevin-khoamai/ragflow/tree/main/rag/"
    click LLMLib "https://github.com/kevin-khoamai/ragflow/tree/main/rag/llm/"
    click NLP "https://github.com/kevin-khoamai/ragflow/tree/main/rag/nlp/"
    click DeepDoc "https://github.com/kevin-khoamai/ragflow/tree/main/deepdoc/"
    click AgentDSL "https://github.com/kevin-khoamai/ragflow/tree/main/agent/"
    click AgentReason "https://github.com/kevin-khoamai/ragflow/tree/main/agentic_reasoning/"
    click SandboxExec "https://github.com/kevin-khoamai/ragflow/tree/main/sandbox/executor_manager/"

    %% Data Stores Layer
    subgraph "Data Stores" 
        direction TB
        MySQL["MySQL (api/db/db_models.py)"]:::data
        MinIO["MinIO (Object Storage)"]:::data
        ES["Elasticsearch / Infinity"]:::data
        Redis["Redis Cache"]:::data
    end

    click MySQL "https://github.com/kevin-khoamai/ragflow/blob/main/api/db/db_models.py"
    click MySQL "https://github.com/kevin-khoamai/ragflow/tree/main/api/db/services/"

    %% Integrations & Plugins Layer
    subgraph "Plugins & Integrations"
        direction TB
        PluginMgr["Plugin Manager\n(plugin/)"]:::external
        EmbeddedPlugins["Embedded Plugins\n(plugin/embedded_plugins/)"]:::external
        Integrations["Integrations\n(intergrations/)"]:::external
    end

    click PluginMgr "https://github.com/kevin-khoamai/ragflow/tree/main/plugin/"
    click EmbeddedPlugins "https://github.com/kevin-khoamai/ragflow/tree/main/plugin/embedded_plugins/"
    click Integrations "https://github.com/kevin-khoamai/ragflow/tree/main/intergrations/"

    %% Deployment Layer
    subgraph "Deployment Manifests"
        direction TB
        DockerCompose["Docker Compose\n(docker/)"]:::external
        HelmCharts["Kubernetes Helm\n(helm/)"]:::external
    end

    click DockerCompose "https://github.com/kevin-khoamai/ragflow/tree/main/docker/"
    click HelmCharts "https://github.com/kevin-khoamai/ragflow/tree/main/helm/"

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["LLM Providers\nOpenAI/Azure/HuggingFace"]:::external
        Tavily["Internet Search\n(Tavily)"]:::external
        Langfuse["Langfuse"]:::external
        MCP["MCP Server"]:::external
    end

    %% Connections
    Browser -->|HTTP/REST| Nginx -->|serves| ReactApp
    ReactApp -->|HTTP/REST| APIGateway
    CLI -->|HTTP/REST| APIGateway
    SDK -->|HTTP/REST| APIGateway

    APIGateway -->|routes| ChatApp
    APIGateway -->|routes| DatasetApp
    APIGateway -->|routes| FileApp
    APIGateway -->|routes| DocumentApp
    APIGateway -->|routes| KBApp
    APIGateway -->|routes| LLMApp
    APIGateway -->|routes| PluginApp
    APIGateway -->|routes| AuthApp

    ChatApp -->|ingest docs| DeepDoc
    DeepDoc -->|store raw| MinIO
    DeepDoc -->|index chunks| ES

    DatasetApp -->|metadata| MySQL
    FileApp -->|blobs| MinIO
    DocumentApp -->|store metadata| MySQL

    KBApp -->|vectors| ES
    KBApp -->|cache| Redis

    LLMApp -->|call| RAGOrch
    RAGOrch -->|use| LLMLib
    RAGOrch -->|use| NLP
    RAGOrch -->|use| AgentDSL
    AgentDSL -->|load modules| AgentReason
    RAGOrch -->|sandbox| SandboxExec

    RAGOrch -->|query| OpenAI
    RAGOrch -->|query| Tavily
    PluginApp -->|callbacks| EmbeddedPlugins
    PluginApp -->|manager| PluginMgr

    %% Data store connections
    ChatApp -->|metadata| MySQL
    DatasetApp -->|metadata| MySQL
    FileApp -->|metadata| MySQL
    AuthApp -->|metadata| MySQL
    LLMApp -->|cache| Redis

    %% Deployment
    APIGateway -.->|docker-compose/helm| DockerCompose
    APIGateway -.->|docker-compose/helm| HelmCharts

    %% Styles
    classDef client fill:#D5F5E3,stroke:#27AE60,color:#1E8449;
    classDef frontend fill:#E8F8F5,stroke:#1ABC9C,color:#117A65;
    classDef api fill:#EBF5FB,stroke:#3498DB,color:#21618C;
    classDef core fill:#FDEDEC,stroke:#E74C3C,color:#C0392B;
    classDef data fill:#F2F4F4,stroke:#95A5A6,color:#566573;
    classDef external fill:#FEF9E7,stroke:#F1C40F,color:#B7950B;
```
