System Architecture

Relevant source files

• README.md
• README_id.md
• README_ja.md
• README_ko.md
• README_pt_br.md
• README_tzh.md
• README_zh.md
• api/apps/api_app.py
• api/apps/chunk_app.py
• api/apps/conversation_app.py
• api/apps/dialog_app.py
• api/apps/document_app.py
• api/apps/file2document_app.py
• api/apps/file_app.py
• api/db/db_models.py
• api/db/services/dialog_service.py
• api/db/services/document_service.py
• api/db/services/file_service.py
• api/db/services/task_service.py
• docker/.env
• docker/README.md
• docs/configurations.md
• docs/guides/manage_files.md
• docs/guides/upgrade_ragflow.mdx
• docs/quickstart.mdx
• rag/nlp/search.py
• rag/svr/task_executor.py

This document provides a high-level overview of RAGFlow's system architecture, describing how the major components are organized, how they communicate, and the deployment model. This serves as an entry point for understanding the system's structure before diving into specific subsystems.

For detailed information about individual services and their responsibilities, see Core Services and Components. For storage backend specifics, see Data Storage and Infrastructure. For deployment procedures, see Deployment and Configuration.

Architectural Style

RAGFlow follows a multi-tier architecture with clear separation between presentation, application logic, data processing, and storage layers. The system is designed for containerized deployment using Docker Compose, with each major component running as an independent service.

Key architectural characteristics:

• Asynchronous Processing: Background task execution separated from API serving via task_executor.py
• Pluggable Storage: Document engine abstraction allows switching between Elasticsearch, OpenSearch, and Infinity
• Multi-Tenancy: Tenant-scoped data isolation enforced at the service layer
• Horizontal Scalability: Stateless API services enable horizontal scaling; background workers can be scaled independently

Sources: README.md136-141 docker/docker-compose-base.yml1-300 api/ragflow_server.py1-120

System Topology

Key Service Endpoints:

Service	Port	Purpose	Implementation
RAGFlow Server	9380	Main REST API, chat, dataset management	api/ragflow_server.py
Admin API	9381	System administration endpoints	conf/service_conf.yaml4-6
MCP Server	9382	Model Context Protocol interface	conf/service_conf.yaml1-3
Document Store	9200 (ES) / 9201 (OS) / 23817 (Infinity)	Vector + full-text search	rag/utils/es_conn.py rag/utils/infinity_conn.py
MySQL	5455	Relational metadata	docker/.env95
MinIO	9000 (API) / 9001 (Console)	Object storage for files	docker/.env106
Redis	6379	Cache, queue, distributed locks	docker/.env118
TEI	6380	Local embedding generation	docker/.env161
Sandbox	9385	Secure code execution	docker/.env228

Sources: docker/.env1-245 conf/service_conf.yaml1-142 docker/docker-compose-base.yml1-300

Component Interaction Patterns

Data Flow Characteristics:

1. Synchronous API Path: ragflow_server.py handles HTTP requests, performs validation, queries MySQL/Redis, and returns responses immediately
2. Asynchronous Processing Path: Heavy operations (parsing, embedding, indexing) are queued to Redis and consumed by task_executor.py
3. Retrieval Path: Chat requests trigger synchronous hybrid search against the document store, followed by LLM generation
4. State Management: MySQL stores metadata and configuration; Redis stores transient state (task queues, locks, caches); MinIO stores raw files; Document store holds searchable chunks

Sources: api/ragflow_server.py50-61 rag/svr/task_executor.py (referenced in diagrams), rag/utils/redis_conn.py1-240

Configuration Architecture

Configuration Hierarchy:

Level	File	Purpose	Example Variables
Docker Environment	docker/.env	Container-level settings, ports, passwords	DOC_ENGINE, MYSQL_PASSWORD, ES_PORT
Service Configuration	docker/service_conf.yaml.template	Application settings with variable substitution	ragflow.host, mysql.max_connections
Compose Orchestration	docker/docker-compose.yml	Service topology, volumes, networks	Service definitions, profiles
Python Settings	common.settings module	Runtime configuration loaded from YAML/env	settings.ES, settings.MYSQL
Dynamic Settings	api/db/runtime_config.py	Database-stored system configuration	System-level toggles

Key Configuration Patterns:

• Variable Substitution: service_conf.yaml.template uses ${VAR_NAME} syntax, populated from .env at container startup
• Profile-Based Deployment: Docker Compose profiles (elasticsearch, infinity, sandbox) enable/disable service groups via COMPOSE_PROFILES
• Singleton Connections: Connection classes (rag/utils/es_conn.py43-83 rag/utils/infinity_conn.py131-159) use @singleton decorator to ensure single instance per process

Sources: docker/.env1-245 docker/service_conf.yaml.template1-142 docker/README.md1-200 api/settings.py1-16

Deployment Architecture

RAGFlow is deployed as a collection of Docker containers orchestrated by Docker Compose. The deployment separates concerns into infrastructure services (databases, storage) and application services (API, workers).

Profile-Based Configuration:

The system uses Docker Compose profiles to enable/disable components based on deployment requirements. Profiles are set via COMPOSE_PROFILES in docker/.env20:

Profile	Purpose	Services Enabled
elasticsearch	Use Elasticsearch as document store	es01 (port 1200)
infinity	Use Infinity as document store	infinity (port 23817)
opensearch	Use OpenSearch as document store	opensearch01 (port 1201)
cpu	CPU-only processing	RAGFlow container with CPU support
gpu	GPU-accelerated processing	RAGFlow container with GPU support
sandbox	Enable code executor	sandbox-executor-manager (port 9385)
tei-cpu / tei-gpu	Local embedding service	Text Embeddings Inference

Container Process Architecture:

The main RAGFlow container runs multiple Python processes:

1. ragflow_server.py (PID 1): HTTP API server handling client requests
2. task_executor.py: Background worker for document processing, embedding generation, and advanced indexing
3. Progress updater thread: Updates document parsing progress in database

Process separation ensures that long-running tasks (document parsing, RAPTOR clustering, GraphRAG entity extraction) do not block API responsiveness.

Sources: docker/docker-compose-base.yml1-300 docker/.env1-245 api/ragflow_server.py46-120 docker/README.md13-22

Data Persistence

All persistent data is stored in Docker volumes, ensuring data survives container restarts:

Volume	Purpose	Content
mysql_data	Relational metadata	Users, tenants, datasets, chat sessions, task records
minio_data	Object storage	Raw uploaded files (PDF, DOCX, images, etc.)
redis_data	Cache and queue data	Task queues, distributed locks, LLM response cache
esdata01 / infinity_data / osdata01	Document store	Indexed text chunks, vector embeddings, full-text indexes

Storage Sizing Considerations:

• Document Store: Largest volume; size depends on number of documents and embedding dimensions. Estimated at ~1-2KB per chunk.
• MinIO: Stores original files; size depends on upload volume
• MySQL: Relatively small; primarily metadata and configuration
• Redis: Ephemeral data; limited by maxmemory setting (docker/docker-compose-base.yml204 sets 128MB default)

Sources: docker/docker-compose-base.yml277-295

Technology Stack Summary

Layer	Technologies	Purpose
Frontend	React, UmiJS, Tailwind CSS, Ant Design	Web UI for knowledge base and chat management
API Server	Flask, Quart (async), Python 3.10-3.12	REST API and Server-Sent Events
Task Processing	Python multiprocessing, Redis queues	Asynchronous background job execution
Document Processing	DeepDoc (ONNX models), pdfplumber, python-docx	OCR, layout analysis, chunking
Vector Search	Elasticsearch 8.11+ OR Infinity OR OpenSearch 2.19+	Hybrid vector + keyword search
Relational DB	MySQL 8.0.39	User, tenant, dataset metadata
Object Storage	MinIO (S3-compatible)	File uploads
Cache/Queue	Redis (Valkey 8)	Distributed locks, task queues, LLM caching
LLM Integration	OpenAI, Anthropic, Cohere, Ollama, etc. (15+ providers)	Chat, embedding, reranking
Graph Processing	NetworkX, graspologic	Entity resolution, community detection
ML/DL	scikit-learn, UMAP, XGBoost, ONNX Runtime	Clustering, chunking, OCR
Containerization	Docker, Docker Compose	Service orchestration

Python Package Dependencies:

Key packages from pyproject.toml9-154:

• Web: flask==3.0.3, quart==0.20.0, flask-cors==5.0.0
• Search: elasticsearch==8.12.1, infinity-sdk==0.6.6, opensearch-py==2.7.1
• Database: pymysql>=1.1.1, peewee==3.17.1, valkey==6.0.2
• Storage: minio==7.2.4, boto3==1.34.140
• LLM: openai>=1.45.0, anthropic==0.34.1, cohere==5.6.2, ollama>=0.5.0
• ML: scikit-learn==1.5.0, umap_learn==0.5.6, xgboost==1.6.0
• Document: pdfplumber==0.10.4, python-docx>=1.1.2, openpyxl>=3.1.0
• NLP: nltk==3.9.1, tiktoken==0.7.0

Sources: pyproject.toml1-199 README.md1-401