# openbmb/ultrarag architecture

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

- Interactive diagram: https://gitdiagram.com/openbmb/ultrarag
- Repository: https://github.com/openbmb/ultrarag

## Overview

UltraRAG combines a visual RAG development environment with a YAML-driven MCP workflow runtime. The main user path is to construct or edit a pipeline, save and build it, then run it as a chat or demo session; the runtime orchestrates modular servers to retrieve knowledge and generate responses. The README also describes knowledge-base management, AI-assisted pipeline development, and standardized evaluation. The excerpts show UI pipeline APIs and portions of backend orchestration, but not all endpoint wiring or runtime implementations, so uncertain links are omitted.

Main entry points: [`src/ultrarag/client.py`](https://github.com/openbmb/ultrarag/blob/main/src/ultrarag/client.py) (MCP Workflow Client), [`ui/frontend/src/pages/BuilderPage.tsx`](https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/pages/BuilderPage.tsx) (Pipeline Builder), [`ui/backend/app.py`](https://github.com/openbmb/ultrarag/blob/main/ui/backend/app.py) (UI Backend), [`ui/frontend/src/shared/api/pipelines.ts`](https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/shared/api/pipelines.ts) (Pipeline API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI and Chat"]
  node_builder["Pipeline Builder<br/>[BuilderPage.tsx]"]
  node_canvas["Pipeline Canvas<br/>[PipelineCanvas.tsx]"]
  node_preview["YAML Preview<br/>[pipelinePreview.ts]"]
  node_pipeline_api["Pipeline API<br/>[pipelines.ts]"]
  node_chat["Chat UI<br/>[ChatPage.tsx]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_chat_store[("Chat Sessions<br/>[chat_store.py]")]
  node_ui_api["UI Backend<br/>[app.py]"]
end

subgraph group_orchestration["Pipeline Orchestration"]
  node_pipeline_manager["Pipeline Manager"]
  node_runtime_client["MCP Workflow Client<br/>[client.py]"]
  node_mcp_server["MCP Server Base<br/>[server.py]"]
end

subgraph group_rag["RAG Components"]
  node_retriever["Retrieval<br/>[retriever.py]"]
  node_corpus["Corpus Processing<br/>[corpus.py]"]
  node_generation["Generation<br/>[generation.py]"]
  node_reranker["Reranking<br/>[reranker.py]"]
  node_prompt_memory["Prompts and Memory<br/>[prompt.py]"]
  node_memory_server["Memory Server<br/>[memory.py]"]
end

subgraph group_research["Research Capabilities"]
  node_evaluation["Evaluation<br/>[evaluation.py]"]
end

node_user(("Developer / User"))
node_model_service{{"Model Provider"}}
node_index_service[("Search Index / Web")]

node_user -->|"designs pipeline"| node_builder
node_user -->|"asks questions"| node_chat
node_builder -->|"edits flow"| node_canvas
node_builder -->|"previews YAML"| node_preview
node_builder -->|"saves / builds"| node_pipeline_api
node_chat -->|"starts chat"| node_pipeline_api
node_pipeline_api -->|"HTTP requests"| node_ui_api
node_ui_api -->|"checks identity"| node_auth
node_ui_api -->|"stores sessions"| node_chat_store
node_ui_api -->|"handles pipeline requests"| node_pipeline_manager
node_pipeline_manager -->|"runs session"| node_runtime_client
node_runtime_client -->|"invokes MCP tools"| node_mcp_server
node_runtime_client -->|"dispatches retrieval"| node_retriever
node_runtime_client -->|"dispatches processing"| node_corpus
node_runtime_client -->|"dispatches generation"| node_generation
node_runtime_client -->|"dispatches reranking"| node_reranker
node_runtime_client -->|"dispatches prompt tools"| node_prompt_memory
node_runtime_client -->|"dispatches memory tools"| node_memory_server
node_retriever -.->|"queries index or web"| node_index_service
node_generation -.->|"requests completion"| node_model_service
node_evaluation -.->|"evaluates outputs"| node_model_service

click node_builder "https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/pages/BuilderPage.tsx"
click node_canvas "https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/features/pipeline/components/PipelineCanvas.tsx"
click node_preview "https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/shared/lib/pipelinePreview.ts"
click node_pipeline_api "https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/shared/api/pipelines.ts"
click node_chat "https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/pages/ChatPage.tsx"
click node_auth "https://github.com/openbmb/ultrarag/blob/main/ui/backend/auth.py"
click node_chat_store "https://github.com/openbmb/ultrarag/blob/main/ui/backend/chat_store.py"
click node_ui_api "https://github.com/openbmb/ultrarag/blob/main/ui/backend/app.py"
click node_pipeline_manager "https://github.com/openbmb/ultrarag/blob/main/ui/backend/pipeline_manager.py"
click node_runtime_client "https://github.com/openbmb/ultrarag/blob/main/src/ultrarag/client.py"
click node_mcp_server "https://github.com/openbmb/ultrarag/blob/main/src/ultrarag/server.py"
click node_retriever "https://github.com/openbmb/ultrarag/blob/main/servers/retriever/src/retriever.py"
click node_corpus "https://github.com/openbmb/ultrarag/blob/main/servers/corpus/src/corpus.py"
click node_generation "https://github.com/openbmb/ultrarag/blob/main/servers/generation/src/generation.py"
click node_reranker "https://github.com/openbmb/ultrarag/blob/main/servers/reranker/src/reranker.py"
click node_prompt_memory "https://github.com/openbmb/ultrarag/blob/main/servers/prompt/src/prompt.py"
click node_memory_server "https://github.com/openbmb/ultrarag/blob/main/servers/memory/src/memory.py"
click node_evaluation "https://github.com/openbmb/ultrarag/blob/main/servers/evaluation/src/evaluation.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_builder,node_canvas,node_preview,node_pipeline_api,node_chat,node_auth,node_chat_store,node_ui_api,node_user toneBlue
class node_pipeline_manager,node_runtime_client,node_mcp_server,node_index_service toneAmber
class node_retriever,node_corpus,node_generation,node_reranker,node_prompt_memory,node_memory_server toneMint
class node_evaluation toneRose
class node_model_service toneIndigo
```

## Components

### UI and Chat

- [Pipeline Builder](https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/pages/BuilderPage.tsx): `ui/frontend/src/pages/BuilderPage.tsx`
- [Pipeline Canvas](https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/features/pipeline/components/PipelineCanvas.tsx): `ui/frontend/src/features/pipeline/components/PipelineCanvas.tsx`
- [YAML Preview](https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/shared/lib/pipelinePreview.ts): `ui/frontend/src/shared/lib/pipelinePreview.ts`
- [Pipeline API](https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/shared/api/pipelines.ts): `ui/frontend/src/shared/api/pipelines.ts`
- [Chat UI](https://github.com/openbmb/ultrarag/blob/main/ui/frontend/src/pages/ChatPage.tsx): `ui/frontend/src/pages/ChatPage.tsx`
- [Authentication](https://github.com/openbmb/ultrarag/blob/main/ui/backend/auth.py): `ui/backend/auth.py`
- [Chat Sessions](https://github.com/openbmb/ultrarag/blob/main/ui/backend/chat_store.py): `ui/backend/chat_store.py`
- [UI Backend](https://github.com/openbmb/ultrarag/blob/main/ui/backend/app.py): `ui/backend/app.py`

### Pipeline Orchestration

- [Pipeline Manager](https://github.com/openbmb/ultrarag/blob/main/ui/backend/pipeline_manager.py): `ui/backend/pipeline_manager.py`
- [MCP Workflow Client](https://github.com/openbmb/ultrarag/blob/main/src/ultrarag/client.py): `src/ultrarag/client.py`
- [MCP Server Base](https://github.com/openbmb/ultrarag/blob/main/src/ultrarag/server.py): `src/ultrarag/server.py`

### RAG Components

- [Retrieval](https://github.com/openbmb/ultrarag/blob/main/servers/retriever/src/retriever.py): `servers/retriever/src/retriever.py`
- [Corpus Processing](https://github.com/openbmb/ultrarag/blob/main/servers/corpus/src/corpus.py): `servers/corpus/src/corpus.py`
- [Generation](https://github.com/openbmb/ultrarag/blob/main/servers/generation/src/generation.py): `servers/generation/src/generation.py`
- [Reranking](https://github.com/openbmb/ultrarag/blob/main/servers/reranker/src/reranker.py): `servers/reranker/src/reranker.py`
- [Prompts and Memory](https://github.com/openbmb/ultrarag/blob/main/servers/prompt/src/prompt.py): `servers/prompt/src/prompt.py`
- [Memory Server](https://github.com/openbmb/ultrarag/blob/main/servers/memory/src/memory.py): `servers/memory/src/memory.py`

### Research Capabilities

- [Evaluation](https://github.com/openbmb/ultrarag/blob/main/servers/evaluation/src/evaluation.py): `servers/evaluation/src/evaluation.py`

### Other components

- **Developer / User**
- **Model Provider**
- **Search Index / Web**

## Connections

- Developer / User → Pipeline Builder: designs pipeline
- Developer / User → Chat UI: asks questions
- Pipeline Builder → Pipeline Canvas: edits flow
- Pipeline Builder → YAML Preview: previews YAML
- Pipeline Builder → Pipeline API: saves / builds
- Chat UI → Pipeline API: starts chat
- Pipeline API → UI Backend: HTTP requests
- UI Backend → Authentication: checks identity
- UI Backend → Chat Sessions: stores sessions
- UI Backend → Pipeline Manager: handles pipeline requests
- Pipeline Manager → MCP Workflow Client: runs session
- MCP Workflow Client → MCP Server Base: invokes MCP tools
- MCP Workflow Client → Retrieval: dispatches retrieval
- MCP Workflow Client → Corpus Processing: dispatches processing
- MCP Workflow Client → Generation: dispatches generation
- MCP Workflow Client → Reranking: dispatches reranking
- MCP Workflow Client → Prompts and Memory: dispatches prompt tools
- MCP Workflow Client → Memory Server: dispatches memory tools
- Retrieval → Search Index / Web: queries index or web
- Generation → Model Provider: requests completion
- Evaluation → Model Provider: evaluates outputs