# ai4finance-foundation/finrag architecture

> Architecture diagram of the GitHub repository ai4finance-foundation/finrag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai4finance-foundation/finrag
- Repository: https://github.com/ai4finance-foundation/finrag

## Overview

FinRAG serves open-domain and knowledge-base chat through a FastAPI endpoint. For knowledge-base updates, the server delegates document processing and vector insertion to the Milvus client; for RAG queries, that client embeds the query, retrieves relevant chunks, optionally reranks results, and asks the chat model to answer. The API also returns suggested questions and can notify a backend when an update completes. Evidence is limited to the README and indexed excerpts; unsampled modules are included only where their role is supported by the tree or documentation.

Main entry points: [`app/core/vectorstore/customer_milvus_client.py`](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/vectorstore/customer_milvus_client.py) (Milvus client), [`app/finrag_server.py`](https://github.com/ai4finance-foundation/finrag/blob/master/app/finrag_server.py) (FastAPI endpoints), [`app/core/preprocessor/file_processor.py`](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/preprocessor/file_processor.py) (File processor), [`app/oss/download_file.py`](https://github.com/ai4finance-foundation/finrag/blob/master/app/oss/download_file.py) (File downloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_server["FastAPI endpoints<br/>[finrag_server.py]"]
  node_status["API status responses<br/>[status.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_processor["File processor<br/>[file_processor.py]"]
  node_splitter["Chinese text splitter"]
  node_title_enhance["Title enhancement"]
  node_downloader["File downloader<br/>[download_file.py]"]
end

subgraph group_retrieval["Retrieval and generation"]
  node_milvus_client["Milvus client"]
  node_embedding["Embedding client"]
  node_reranker["Rerank client<br/>[rerank_client.py]"]
  node_openchat["Open chat client<br/>[open_chat.py]"]
  node_rag_chat["RAG chat module<br/>[rag_chat.py]"]
end

subgraph group_integrations["External services and settings"]
  node_milvus[("Milvus database")]
  node_storage[("File storage")]
  node_llm["DashScope Qwen API"]
  node_notify_service["Completion callback service"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_user(("Chat or update caller"))

node_user -->|"calls endpoint"| node_server
node_server -->|"delegates RAG and updates"| node_milvus_client
node_server -->|"requests chat"| node_openchat
node_server -->|"returns update status"| node_status
node_server -->|"posts completion"| node_notify_service
node_milvus_client -->|"processes downloaded files"| node_processor
node_processor -->|"splits documents"| node_splitter
node_milvus_client -->|"downloads source files"| node_downloader
node_downloader -->|"copies or fetches files"| node_storage
node_milvus_client -->|"embeds chunks and queries"| node_embedding
node_milvus_client -->|"inserts and searches"| node_milvus
node_milvus_client -->|"reranks candidates"| node_reranker
node_milvus_client -->|"generates RAG answer"| node_openchat
node_openchat -->|"calls chat API"| node_llm
node_server -->|"reads settings"| node_config
node_milvus_client -->|"reads vector settings"| node_config
node_downloader -->|"reads storage settings"| node_config
node_processor -.-> node_title_enhance

click node_server "https://github.com/ai4finance-foundation/finrag/blob/master/app/finrag_server.py"
click node_status "https://github.com/ai4finance-foundation/finrag/blob/master/app/models/status.py"
click node_milvus_client "https://github.com/ai4finance-foundation/finrag/blob/master/app/core/vectorstore/customer_milvus_client.py"
click node_processor "https://github.com/ai4finance-foundation/finrag/blob/master/app/core/preprocessor/file_processor.py"
click node_splitter "https://github.com/ai4finance-foundation/finrag/blob/master/app/core/splitter/chinese_text_splitter.py"
click node_title_enhance "https://github.com/ai4finance-foundation/finrag/blob/master/app/core/splitter/zh_title_enhance.py"
click node_downloader "https://github.com/ai4finance-foundation/finrag/blob/master/app/oss/download_file.py"
click node_embedding "https://github.com/ai4finance-foundation/finrag/blob/master/app/core/bce/embedding_client.py"
click node_reranker "https://github.com/ai4finance-foundation/finrag/blob/master/app/core/bce/rerank_client.py"
click node_openchat "https://github.com/ai4finance-foundation/finrag/blob/master/app/core/chat/open_chat.py"
click node_rag_chat "https://github.com/ai4finance-foundation/finrag/blob/master/app/core/chat/rag_chat.py"
click node_config "https://github.com/ai4finance-foundation/finrag/blob/master/conf/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_status toneBlue
class node_processor,node_splitter,node_title_enhance,node_downloader toneAmber
class node_milvus_client,node_embedding,node_reranker,node_openchat,node_rag_chat toneMint
class node_milvus,node_storage,node_llm,node_notify_service,node_config toneRose
class node_user toneIndigo
```

## Components

### API and orchestration

- [FastAPI endpoints](https://github.com/ai4finance-foundation/finrag/blob/master/app/finrag_server.py): `app/finrag_server.py`
- [API status responses](https://github.com/ai4finance-foundation/finrag/blob/master/app/models/status.py): `app/models/status.py`

### Document ingestion

- [File processor](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/preprocessor/file_processor.py): `app/core/preprocessor/file_processor.py`
- [Chinese text splitter](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/splitter/chinese_text_splitter.py): `app/core/splitter/chinese_text_splitter.py`
- [Title enhancement](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/splitter/zh_title_enhance.py): `app/core/splitter/zh_title_enhance.py`
- [File downloader](https://github.com/ai4finance-foundation/finrag/blob/master/app/oss/download_file.py): `app/oss/download_file.py`

### Retrieval and generation

- [Milvus client](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/vectorstore/customer_milvus_client.py): `app/core/vectorstore/customer_milvus_client.py`
- [Embedding client](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/bce/embedding_client.py): `app/core/bce/embedding_client.py`
- [Rerank client](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/bce/rerank_client.py): `app/core/bce/rerank_client.py`
- [Open chat client](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/chat/open_chat.py): `app/core/chat/open_chat.py`
- [RAG chat module](https://github.com/ai4finance-foundation/finrag/blob/master/app/core/chat/rag_chat.py): `app/core/chat/rag_chat.py`

### External services and settings

- **Milvus database**
- **File storage**
- **DashScope Qwen API**
- **Completion callback service**
- [Runtime configuration](https://github.com/ai4finance-foundation/finrag/blob/master/conf/config.py): `conf/config.py`

### Other components

- **Chat or update caller**

## Connections

- Chat or update caller → FastAPI endpoints: calls endpoint (evidence: `app/finrag_server.py`)
- FastAPI endpoints → Milvus client: delegates RAG and updates (evidence: `app/finrag_server.py`)
- FastAPI endpoints → Open chat client: requests chat (evidence: `app/finrag_server.py`)
- FastAPI endpoints → API status responses: returns update status (evidence: `app/finrag_server.py`)
- FastAPI endpoints → Completion callback service: posts completion (evidence: `app/finrag_server.py`)
- Milvus client → File processor: processes downloaded files (evidence: `app/core/vectorstore/customer_milvus_client.py`)
- File processor → Chinese text splitter: splits documents (evidence: `app/core/preprocessor/file_processor.py`)
- Milvus client → File downloader: downloads source files (evidence: `app/core/vectorstore/customer_milvus_client.py`)
- File downloader → File storage: copies or fetches files (evidence: `app/oss/download_file.py`)
- Milvus client → Embedding client: embeds chunks and queries (evidence: `app/core/vectorstore/customer_milvus_client.py`)
- Milvus client → Milvus database: inserts and searches (evidence: `app/core/vectorstore/customer_milvus_client.py`)
- Milvus client → Rerank client: reranks candidates (evidence: `app/core/vectorstore/customer_milvus_client.py`)
- Milvus client → Open chat client: generates RAG answer (evidence: `app/core/vectorstore/customer_milvus_client.py`)
- Open chat client → DashScope Qwen API: calls chat API (evidence: `app/core/chat/open_chat.py`)
- FastAPI endpoints → Runtime configuration: reads settings (evidence: `app/finrag_server.py`)
- Milvus client → Runtime configuration: reads vector settings (evidence: `app/core/vectorstore/customer_milvus_client.py`)
- File downloader → Runtime configuration: reads storage settings (evidence: `app/oss/download_file.py`)
- File processor → Title enhancement (evidence: `app/core/preprocessor/file_processor.py`)