System Architecture

Relevant source files

• admin/server/admin_server.py
• api/db/__init__.py
• api/db/db_models.py
• api/db/services/dialog_service.py
• api/db/services/document_service.py
• api/db/services/knowledgebase_service.py
• api/db/services/task_service.py
• api/db/services/user_service.py
• api/ragflow_server.py
• cmd/ragflow_server.go
• conf/service_conf.yaml
• docker/service_conf.yaml.template
• go.mod
• go.sum
• internal/admin/handler.go
• internal/admin/handler_ee.go
• internal/admin/router_ee.go
• internal/admin/service.go
• internal/admin/service_ee.go
• internal/common/error_code.go
• internal/common/http.go
• internal/common/version.go
• internal/common/version_ee.go
• internal/common/version_test.go
• internal/dao/user.go
• internal/engine/clickhouse/clickhouse_ee.go
• internal/engine/infinity/chunk.go
• internal/engine/infinity/client.go
• internal/engine/infinity/client_test.go
• internal/engine/infinity/common.go
• internal/engine/infinity/document.go
• internal/engine/infinity/metadata.go
• internal/handler/user.go
• internal/ingestion/registry/cross_domain_test.go
• internal/router/router_ee.go
• internal/server/config.go
• internal/server/server_ee.go
• internal/service/user.go
• internal/utility/token.go
• rag/nlp/query.py
• rag/nlp/rag_tokenizer.py
• rag/nlp/search.py
• rag/nlp/term_weight.py
• rag/svr/task_executor.py
• rag/utils/redis_conn.py

Purpose and Scope

This document provides an in-depth overview of RAGFlow's layered architecture, describing how the API gateway, service layer, worker layer, and storage layer interact to deliver document-based conversational AI capabilities. RAGFlow is a retrieval-augmented generation engine that combines deep document understanding with agentic workflows.

For specific implementation details:

• Core application services and request routing: see Core Application Services
• Storage layer design and database selection: see Data Storage Architecture
• Asynchronous task processing: see Task Execution and Queue System
• Agent and tool component loading: see Component Dynamic Loading
• Go-based native service layer: see Go Server and Native Components
• Go-native agent canvas and workflow engine: see Go Agent Port
• Go-native agent framework: see Go Harness Agent Framework

For frontend architecture, see Frontend Application. For LLM integration patterns, see LLM Integration System. For document processing pipelines, see Document Processing Pipeline.

---

Overview

RAGFlow employs a five-layer microservices architecture that separates concerns across client interaction, API routing, business logic, asynchronous processing, and data persistence. The system is designed for horizontal scalability with stateless API servers and distributed worker processes communicating through Redis-backed message queues or NATS conf/service_conf.yaml51-70

The architecture follows these principles:

• Separation of concerns: API servers handle synchronous requests; workers run long-lived asynchronous tasks such as document parsing and embedding generation managed via message queues api/ragflow_server.py134-160
• Pluggable components: Document stores (Elasticsearch, Infinity, OceanBase, or OpenSearch) are selectable via configuration conf/service_conf.yaml22-45
• Multi-tenancy: All data is scoped by tenants, with specific configurations for user_default_llm and default models conf/service_conf.yaml74-80
• Hybrid Backend: A high-performance Go-based native service layer and agent engine complement the Python backend. The Go server supports multiple modes including --api, --admin, --ingestor, and --syncer cmd/ragflow_server.go81-94

---

Five-Layer Architecture

System Component Diagram

This diagram illustrates RAGFlow's modular subsystems and code entity mapping:

Sources:
api/ragflow_server.py163-165 cmd/ragflow_server.go81-94 conf/service_conf.yaml7-55 rag/utils/redis_conn.py61-114

---

Core Execution Flows

Document Upload and Progress Tracking

A client uploads a document via the API server. The DocumentService handles metadata while the system tracks progress asynchronously. A dedicated thread in the Python server periodically updates processing progress api/ragflow_server.py55-71

Sources:
api/ragflow_server.py55-71 api/ragflow_server.py134-138 conf/service_conf.yaml67-70

---

Core Components by Layer

Layer 1: Client Layer

Provides external interfaces. The Python SDK and Direct HTTP APIs interact with the ragflow service api/ragflow_server.py17-36

Layer 2: API Gateway

Manages synchronous requests. RAGFlow supports a dual-language entry point:

• Python: api/ragflow_server.py using Quart, initialized with database tables and superuser data api/ragflow_server.py106-121
• Go: cmd/ragflow_server.go which handles --api and --admin modes cmd/ragflow_server.go81-94

Layer 3: Service Layer

Encapsulates business logic. The Python side uses a service pattern (e.g., DocumentService api/db/services/document_service.py42-73), while the Go side provides a native internal/service/ layer for NLP and search internal/admin/handler.go25-30

Layer 4: Worker Layer

Background workers process tasks from NATS or Redis Streams. The TaskExecutor in Python processes parsing, embedding, and GraphRAG tasks rag/svr/task_executor.py114-147 The Go-native ingestor handles document processing pipelines cmd/ragflow_server.go188-200

Layer 5: Storage Layer

A polyglot strategy using:

• Relational: MySQL for metadata, with max_connections and stale_timeout tuning conf/service_conf.yaml7-15
• Document Store: Elasticsearch, Infinity, or OceanBase for hybrid search conf/service_conf.yaml22-45
• Cache/Queue: Redis/Valkey for distributed locking and task management rag/utils/redis_conn.py61-114

---

Bridging Natural Language to Code

Diagram: Natural Language Space to Code Entity Space

This diagram maps high-level system concepts to specific Go and Python entities.

Sources:
internal/server/config.go19-30 rag/utils/redis_conn.py61-64 rag/svr/task_executor.py114-131 internal/admin/handler.go94-137 rag/nlp/search.py39-54

---

Summary

RAGFlow's architecture provides a modular, scalable platform to deliver retrieval-augmented generation. By utilizing a hybrid Python-Go backend, it balances the rapid development of AI features in Python with the high-performance execution of ingestion and agent workflows in Go.

Sources:
api/ragflow_server.py82-165 cmd/ragflow_server.go81-94 conf/service_conf.yaml1-80