# sciphi-ai/r2r architecture

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

- Interactive diagram: https://gitdiagram.com/sciphi-ai/r2r
- Repository: https://github.com/sciphi-ai/r2r

## Overview

#### Purpose and Entry Points
R2R is a self-hostable, REST-oriented AI retrieval platform: multimodal document ingestion, hybrid/vector retrieval, RAG and research agents, knowledge graphs, and multi-user document/collection management. The Python server starts through `py/r2r/serve.py` and assembles the application in `py/core/main/app_entry.py` / `py/core/main/app.py`. Consumers use Python and TypeScript SDKs via `py/sdk/sync_client.py`, `py/sdk/async_client.py`, and `js/sdk/src/r2rClient.ts`.

#### API and Application Assembly
Versioned HTTP endpoints are separated by resource domain—documents, chunks, collections, retrieval, graphs, conversations, users, prompts, indices, and system. Routers should remain thin API boundaries over services:
- `py/core/main/api/v3/documents_router.py`
- `py/core/main/api/v3/retrieval_router.py`
- `py/core/main/api/v3/graph_router.py`

`py/core/main/assembly/builder.py` and `py/core/main/assembly/factory.py` select and wire provider implementations from runtime configuration, allowing light/local versus full/deployed installations without changing service callers.

#### Service Layer and Core Flows
Services contain use-case orchestration between routers, providers, and background workflows:
- `py/core/main/services/ingestion_service.py`
- `py/core/main/services/retrieval_service.py`
- `py/core/main/services/graph_service.py`

Primary ingestion flow is API/SDK request → ingestion service → file/ingestion provider and format parser → chunking/embedding → PostgreSQL-backed document/chunk/vector persistence; graph extraction can be scheduled from ingested content. Retrieval flows are API → retrieval service → database hybrid search and LLM/agent generation, returning search results or cited RAG output. Authorization, ownership, collections, limits, and prompts constrain these operations.

#### Ingestion and Knowledge Construction
The parser layer supports media, structured, and text inputs, while provider interfaces isolate parser/ingestion implementations:
- `py/core/parsers/media/pdf_parser.py`
- `py/core/providers/ingestion/r2r/base.py`
- `py/core/providers/ingestion/unstructured/base.py`

Document text is split through shared abstractions, embedded through configured models, and stored as searchable chunks. Graph workflows perform entity/relationship extraction and community-oriented graph processing:
- `py/core/main/orchestration/hatchet/ingestion_workflow.py`
- `py/core/main/orchestration/hatchet/graph_workflow.py`
- `py/shared/abstractions/graph.py`

#### Retrieval, RAG, and Agents
Retrieval combines semantic/vector and keyword-oriented database capabilities, with prompt-driven RAG and tool-using agents:
- `py/core/agent/rag.py`
- `py/core/agent/research.py`
- `py/core/providers/database/postgres.py`

Agent tools include knowledge/file search and web acquisition, creating an explicit boundary between tenant knowledge-base retrieval and internet-backed research:
- `py/core/base/agent/tools/built_in/search_file_knowledge.py`
- `py/core/base/agent/tools/built_in/web_search.py`
- `py/core/base/agent/tools/built_in/tavily_search.py`

#### Provider and Persistence Boundaries
Abstract provider contracts in `py/core/base/providers/` decouple application logic from concrete integrations. Implementations cover PostgreSQL/pgvector data, S3 or PostgreSQL file storage, OpenAI/LiteLLM/Ollama/Anthropic/Azure model access, OCR, auth, email, and scheduling. Key implementations:
- `py/core/providers/database/postgres.py`
- `py/core/providers/embeddings/openai.py`
- `py/core/providers/llm/litellm.py`

PostgreSQL schema evolution is managed under `py/migrations/`. Authentication supports internal JWT/R2R auth and external Clerk/Supabase alternatives.

#### Deployment and Runtime Topology
Light mode runs the Python service with local/simple providers. Full Docker and Kubernetes deployments provision R2R alongside PostgreSQL/pgvector, Hatchet orchestration with RabbitMQ, MinIO-compatible object storage, optional Unstructured parsing, and a separate graph-clustering service:
- `docker/compose.full.yaml`
- `deployment/k8s/kustomizations/kustomization.yaml`
- `services/clustering/main.py`

Hatchet is the durable asynchronous-workflow boundary for long-running ingestion and graph jobs; `simple` orchestration offers an in-process alternative. Production observability includes Fluent Bit configuration and optional Sentry integration.

Main entry points: [`docker/compose.full.yaml`](https://github.com/sciphi-ai/r2r/blob/main/docker/compose.full.yaml) (Full Docker/Kubernetes topology), [`py/core/providers/ingestion/r2r/base.py`](https://github.com/sciphi-ai/r2r/blob/main/py/core/providers/ingestion/r2r/base.py) (Ingestion pipeline), [`py/core/providers/database/postgres.py`](https://github.com/sciphi-ai/r2r/blob/main/py/core/providers/database/postgres.py) (PostgreSQL + pgvector), [`py/core/main/services/ingestion_service.py`](https://github.com/sciphi-ai/r2r/blob/main/py/core/main/services/ingestion_service.py) (Application services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_python_sdk["Python SDKs<br/>client SDK<br/>[sync_client.py]"]
  node_typescript_sdk["TypeScript SDK<br/>client SDK<br/>[r2rClient.ts]"]
end

subgraph group_application["Python application"]
  node_server["R2R server<br/>entry point<br/>[serve.py]"]
  node_app["Application assembly<br/>app composition<br/>[app_entry.py]"]
  node_routers["Versioned API routers<br/>REST boundary"]
  node_services["Application services<br/>use-case layer"]
  node_ingestion["Ingestion pipeline<br/>document processing<br/>[base.py]"]
  node_pdf_parser["Format parsers<br/>parser layer<br/>[pdf_parser.py]"]
  node_retrieval["RAG and research agents<br/>agent layer<br/>[rag.py]"]
  node_knowledge_search["Knowledge search tool<br/>agent tool"]
  node_web_search["Web research tools<br/>agent tool<br/>[web_search.py]"]
end

subgraph group_providers["Providers and data"]
  node_builder["Provider builder<br/>runtime wiring<br/>[builder.py]"]
  node_provider_contracts["Provider contracts<br/>abstractions"]
  node_models["LLM and embedding providers<br/>AI integrations<br/>[litellm.py]"]
  node_postgres[("PostgreSQL + pgvector<br/>persistence and search<br/>[postgres.py]")]
  node_object_storage[("Object storage<br/>file persistence")]
end

subgraph group_async["Async knowledge workflows"]
  node_hatchet_workflows["Hatchet workflows<br/>durable orchestration"]
  node_graph_processing["Knowledge graph processing<br/>graph workflow<br/>[graph_workflow.py]"]
end

subgraph group_deployment["Full deployment services"]
  node_clustering{{"Graph clustering service<br/>separate service<br/>[main.py]"}}
  node_full_deployment["Full Docker/Kubernetes topology<br/>deployment definition<br/>[compose.full.yaml]"]
end

node_python_sdk -->|"REST requests"| node_routers
node_typescript_sdk -->|"REST requests"| node_routers
node_server -->|"starts"| node_app
node_app -->|"mounts"| node_routers
node_app -->|"configures"| node_builder
node_routers -->|"delegates"| node_services
node_services -->|"ingests documents"| node_ingestion
node_ingestion -->|"parses content"| node_pdf_parser
node_ingestion -->|"embeds chunks"| node_models
node_ingestion -->|"persists chunks and vectors"| node_postgres
node_ingestion -->|"stores files"| node_object_storage
node_services -->|"runs retrieval and RAG"| node_retrieval
node_retrieval -->|"tenant knowledge"| node_knowledge_search
node_knowledge_search -->|"hybrid search"| node_postgres
node_retrieval -->|"internet research"| node_web_search
node_retrieval -->|"generation"| node_models
node_builder -->|"binds implementations"| node_provider_contracts
node_provider_contracts -.->|"model contracts"| node_models
node_provider_contracts -.->|"database contract"| node_postgres
node_services -->|"schedules long jobs"| node_hatchet_workflows
node_hatchet_workflows -->|"runs graph jobs"| node_graph_processing
node_graph_processing -->|"stores graph data"| node_postgres
node_graph_processing -->|"community clustering"| node_clustering
node_full_deployment -.->|"deploys"| node_server
node_full_deployment -.->|"provisions"| node_hatchet_workflows
node_full_deployment -.->|"provisions"| node_postgres
node_full_deployment -.->|"provisions"| node_object_storage
node_full_deployment -.->|"provisions"| node_clustering

click node_python_sdk "https://github.com/sciphi-ai/r2r/blob/main/py/sdk/sync_client.py"
click node_typescript_sdk "https://github.com/sciphi-ai/r2r/blob/main/js/sdk/src/r2rClient.ts"
click node_server "https://github.com/sciphi-ai/r2r/blob/main/py/r2r/serve.py"
click node_app "https://github.com/sciphi-ai/r2r/blob/main/py/core/main/app_entry.py"
click node_routers "https://github.com/sciphi-ai/r2r/blob/main/py/core/main/api/v3/documents_router.py"
click node_services "https://github.com/sciphi-ai/r2r/blob/main/py/core/main/services/ingestion_service.py"
click node_ingestion "https://github.com/sciphi-ai/r2r/blob/main/py/core/providers/ingestion/r2r/base.py"
click node_pdf_parser "https://github.com/sciphi-ai/r2r/blob/main/py/core/parsers/media/pdf_parser.py"
click node_retrieval "https://github.com/sciphi-ai/r2r/blob/main/py/core/agent/rag.py"
click node_knowledge_search "https://github.com/sciphi-ai/r2r/blob/main/py/core/base/agent/tools/built_in/search_file_knowledge.py"
click node_web_search "https://github.com/sciphi-ai/r2r/blob/main/py/core/base/agent/tools/built_in/web_search.py"
click node_builder "https://github.com/sciphi-ai/r2r/blob/main/py/core/main/assembly/builder.py"
click node_models "https://github.com/sciphi-ai/r2r/blob/main/py/core/providers/llm/litellm.py"
click node_postgres "https://github.com/sciphi-ai/r2r/blob/main/py/core/providers/database/postgres.py"
click node_hatchet_workflows "https://github.com/sciphi-ai/r2r/blob/main/py/core/main/orchestration/hatchet/ingestion_workflow.py"
click node_graph_processing "https://github.com/sciphi-ai/r2r/blob/main/py/core/main/orchestration/hatchet/graph_workflow.py"
click node_clustering "https://github.com/sciphi-ai/r2r/blob/main/services/clustering/main.py"
click node_full_deployment "https://github.com/sciphi-ai/r2r/blob/main/docker/compose.full.yaml"

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_python_sdk,node_typescript_sdk toneBlue
class node_server,node_app,node_routers,node_services,node_ingestion,node_pdf_parser,node_retrieval,node_knowledge_search,node_web_search toneAmber
class node_builder,node_provider_contracts,node_models,node_postgres,node_object_storage toneMint
class node_hatchet_workflows,node_graph_processing toneRose
class node_clustering,node_full_deployment toneIndigo
```

## Components

### Clients

- [Python SDKs](https://github.com/sciphi-ai/r2r/blob/main/py/sdk/sync_client.py): client SDK · `py/sdk/sync_client.py`
- [TypeScript SDK](https://github.com/sciphi-ai/r2r/blob/main/js/sdk/src/r2rClient.ts): client SDK · `js/sdk/src/r2rClient.ts`

### Python application

- [R2R server](https://github.com/sciphi-ai/r2r/blob/main/py/r2r/serve.py): entry point · `py/r2r/serve.py`
- [Application assembly](https://github.com/sciphi-ai/r2r/blob/main/py/core/main/app_entry.py): app composition · Builds the REST application and selected runtime components. · `py/core/main/app_entry.py`
- [Versioned API routers](https://github.com/sciphi-ai/r2r/blob/main/py/core/main/api/v3/documents_router.py): REST boundary · Resource routers remain thin boundaries over services. · `py/core/main/api/v3/documents_router.py`
- [Application services](https://github.com/sciphi-ai/r2r/blob/main/py/core/main/services/ingestion_service.py): use-case layer · Applies authorization, ownership, collections, limits, and prompts. · `py/core/main/services/ingestion_service.py`
- [Ingestion pipeline](https://github.com/sciphi-ai/r2r/blob/main/py/core/providers/ingestion/r2r/base.py): document processing · Parses inputs, chunks text, and creates embeddings. · `py/core/providers/ingestion/r2r/base.py`
- [Format parsers](https://github.com/sciphi-ai/r2r/blob/main/py/core/parsers/media/pdf_parser.py): parser layer · Handles media, structured, and text inputs. · `py/core/parsers/media/pdf_parser.py`
- [RAG and research agents](https://github.com/sciphi-ai/r2r/blob/main/py/core/agent/rag.py): agent layer · Produces cited RAG responses and tool-using research. · `py/core/agent/rag.py`
- [Knowledge search tool](https://github.com/sciphi-ai/r2r/blob/main/py/core/base/agent/tools/built_in/search_file_knowledge.py): agent tool · `py/core/base/agent/tools/built_in/search_file_knowledge.py`
- [Web research tools](https://github.com/sciphi-ai/r2r/blob/main/py/core/base/agent/tools/built_in/web_search.py): agent tool · Explicit internet acquisition boundary. · `py/core/base/agent/tools/built_in/web_search.py`

### Providers and data

- [Provider builder](https://github.com/sciphi-ai/r2r/blob/main/py/core/main/assembly/builder.py): runtime wiring · Selects implementations for light or deployed installations. · `py/core/main/assembly/builder.py`
- **Provider contracts**: abstractions · Decouple services from database, model, storage, auth, and scheduler integrations.
- [LLM and embedding providers](https://github.com/sciphi-ai/r2r/blob/main/py/core/providers/llm/litellm.py): AI integrations · `py/core/providers/llm/litellm.py`
- [PostgreSQL + pgvector](https://github.com/sciphi-ai/r2r/blob/main/py/core/providers/database/postgres.py): persistence and search · Stores documents, chunks, vectors, metadata, and supports hybrid search. · `py/core/providers/database/postgres.py`
- **Object storage**: file persistence · S3- or PostgreSQL-backed file storage.

### Async knowledge workflows

- [Hatchet workflows](https://github.com/sciphi-ai/r2r/blob/main/py/core/main/orchestration/hatchet/ingestion_workflow.py): durable orchestration · Runs long-lived ingestion and graph extraction jobs. · `py/core/main/orchestration/hatchet/ingestion_workflow.py`
- [Knowledge graph processing](https://github.com/sciphi-ai/r2r/blob/main/py/core/main/orchestration/hatchet/graph_workflow.py): graph workflow · Extracts entities and relationships and performs community processing. · `py/core/main/orchestration/hatchet/graph_workflow.py`

### Full deployment services

- [Graph clustering service](https://github.com/sciphi-ai/r2r/blob/main/services/clustering/main.py): separate service · `services/clustering/main.py`
- [Full Docker/Kubernetes topology](https://github.com/sciphi-ai/r2r/blob/main/docker/compose.full.yaml): deployment definition · Provisions R2R with PostgreSQL, Hatchet/RabbitMQ, storage, and optional parsing. · `docker/compose.full.yaml`

## Connections

- Python SDKs → Versioned API routers: REST requests
- TypeScript SDK → Versioned API routers: REST requests
- R2R server → Application assembly: starts
- Application assembly → Versioned API routers: mounts
- Application assembly → Provider builder: configures
- Versioned API routers → Application services: delegates
- Application services → Ingestion pipeline: ingests documents
- Ingestion pipeline → Format parsers: parses content
- Ingestion pipeline → LLM and embedding providers: embeds chunks
- Ingestion pipeline → PostgreSQL + pgvector: persists chunks and vectors
- Ingestion pipeline → Object storage: stores files
- Application services → RAG and research agents: runs retrieval and RAG
- RAG and research agents → Knowledge search tool: tenant knowledge
- Knowledge search tool → PostgreSQL + pgvector: hybrid search
- RAG and research agents → Web research tools: internet research
- RAG and research agents → LLM and embedding providers: generation
- Provider builder → Provider contracts: binds implementations
- Provider contracts → LLM and embedding providers: model contracts
- Provider contracts → PostgreSQL + pgvector: database contract
- Application services → Hatchet workflows: schedules long jobs
- Hatchet workflows → Knowledge graph processing: runs graph jobs
- Knowledge graph processing → PostgreSQL + pgvector: stores graph data
- Knowledge graph processing → Graph clustering service: community clustering
- Full Docker/Kubernetes topology → R2R server: deploys
- Full Docker/Kubernetes topology → Hatchet workflows: provisions
- Full Docker/Kubernetes topology → PostgreSQL + pgvector: provisions
- Full Docker/Kubernetes topology → Object storage: provisions
- Full Docker/Kubernetes topology → Graph clustering service: provisions
