# reaatech/hybrid-rag architecture

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

- Interactive diagram: https://gitdiagram.com/reaatech/hybrid-rag
- Repository: https://github.com/reaatech/hybrid-rag

## Overview

hybrid-rag is a TypeScript RAG monorepo: clients submit documents or queries through the CLI, MCP tools, or the pipeline API. The pipeline coordinates ingestion, embeddings, and hybrid retrieval over configurable vector stores; retrieval combines semantic and BM25 results, with optional reranking. Separate packages provide migration, evaluation, benchmarking, ablation, and observability. The README documents the overall capabilities; source-index references and excerpts support the detailed pipeline, chunking, retrieval, and adapter relationships shown here. Other subsystem internals were not sampled.

Main entry points: [`packages/hybrid-rag-pipeline/src/pipeline.ts`](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-pipeline/src/pipeline.ts) (RAG pipeline), [`packages/hybrid-rag-retrieval/src/fusion/hybrid-retriever.ts`](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/fusion/hybrid-retriever.ts) (Hybrid retriever), [`packages/hybrid-rag-evaluation/src/runner.ts`](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/runner.ts) (Evaluation runner), [`packages/hybrid-rag-qdrant/src/qdrant-client.ts`](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-qdrant/src/qdrant-client.ts) (15 vector adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[index.ts]"]
  node_mcp["MCP server<br/>[mcp-server.ts]"]
  node_pipeline["RAG pipeline<br/>[pipeline.ts]"]
  node_core["Core types<br/>[domain.ts]"]
end

subgraph group_ingestion["Document ingestion"]
  node_loader["Document loading<br/>[loader.ts]"]
  node_preprocessor["Preprocessing<br/>[preprocessor.ts]"]
  node_chunking["Chunking engine<br/>[chunking-engine.ts]"]
  node_strategies["Chunk strategies"]
end

subgraph group_retrieval["Hybrid retrieval"]
  node_embedding["Embedding service<br/>[embedding.ts]"]
  node_hybrid["Hybrid retriever"]
  node_vectorsearch["Vector search<br/>[vector-search.ts]"]
  node_bm25["BM25 search<br/>[search.ts]"]
  node_tokenizer["BM25 tokenizer<br/>[tokenizer.ts]"]
  node_fusion["Fusion and reranking<br/>[engine.ts]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.ts]"]
end

subgraph group_storage["Vector storage"]
  node_factory["Store selection"]
  node_stores["15 vector adapters<br/>[qdrant-client.ts]"]
  node_migration["Store migration<br/>[migration.ts]"]
end

subgraph group_operations["Evaluation and operations"]
  node_evaluation["Evaluation runner<br/>[runner.ts]"]
  node_metrics["Retrieval metrics<br/>[retrieval.ts]"]
  node_ablation["Ablation studies<br/>[runner.ts]"]
  node_benchmark["Performance benchmarks<br/>[db-benchmark.ts]"]
  node_observability["Observability<br/>[logger.ts]"]
end

node_user(("RAG user"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses agent tools"| node_mcp
node_user -->|"calls API"| node_pipeline
node_cli -->|"ingests and queries"| node_pipeline
node_mcp -->|"provides RAG tools"| node_pipeline
node_pipeline -->|"chunks documents"| node_chunking
node_pipeline -->|"generates embeddings"| node_embedding
node_pipeline -->|"runs retrieval"| node_hybrid
node_pipeline -->|"creates store"| node_factory
node_loader -.->|"prepares documents"| node_preprocessor
node_chunking -->|"dispatches strategy"| node_strategies
node_hybrid -->|"searches vectors"| node_vectorsearch
node_hybrid -->|"searches keywords"| node_bm25
node_hybrid -->|"fuses results"| node_fusion
node_bm25 -->|"tokenizes text"| node_tokenizer
node_fusion -->|"reranks results"| node_reranker
node_vectorsearch -->|"embeds queries"| node_embedding
node_factory -.->|"selects provider"| node_stores
node_migration -.->|"moves vectors"| node_stores
node_evaluation -.->|"computes scores"| node_metrics
node_evaluation -.->|"evaluates queries"| node_pipeline
node_ablation -.->|"compares variants"| node_evaluation
node_benchmark -.->|"benchmarks latency"| node_stores

click node_cli "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-cli/src/index.ts"
click node_mcp "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-mcp-server/src/mcp-server.ts"
click node_pipeline "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-pipeline/src/pipeline.ts"
click node_core "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag/src/domain.ts"
click node_loader "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-ingestion/src/loader.ts"
click node_preprocessor "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-ingestion/src/preprocessor.ts"
click node_chunking "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-ingestion/src/chunking-engine.ts"
click node_strategies "https://github.com/reaatech/hybrid-rag/tree/main/packages/hybrid-rag-ingestion/src/chunking-strategies"
click node_embedding "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-embedding/src/embedding.ts"
click node_hybrid "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/fusion/hybrid-retriever.ts"
click node_vectorsearch "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/vector-search.ts"
click node_bm25 "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/bm25/search.ts"
click node_tokenizer "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/bm25/tokenizer.ts"
click node_fusion "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/fusion/engine.ts"
click node_reranker "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/reranker.ts"
click node_factory "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/vector-store-factory.ts"
click node_stores "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-qdrant/src/qdrant-client.ts"
click node_migration "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-migration/src/migration.ts"
click node_evaluation "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/runner.ts"
click node_metrics "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/metrics/retrieval.ts"
click node_ablation "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/ablation/runner.ts"
click node_benchmark "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/benchmarking/db-benchmark.ts"
click node_observability "https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-observability/src/logger.ts"

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_cli,node_mcp,node_pipeline,node_core,node_user toneBlue
class node_loader,node_preprocessor,node_chunking,node_strategies toneAmber
class node_embedding,node_hybrid,node_vectorsearch,node_bm25,node_tokenizer,node_fusion,node_reranker toneMint
class node_factory,node_stores,node_migration toneRose
class node_evaluation,node_metrics,node_ablation,node_benchmark,node_observability toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-cli/src/index.ts): `packages/hybrid-rag-cli/src/index.ts`
- [MCP server](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-mcp-server/src/mcp-server.ts): `packages/hybrid-rag-mcp-server/src/mcp-server.ts`
- [RAG pipeline](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-pipeline/src/pipeline.ts): `packages/hybrid-rag-pipeline/src/pipeline.ts`
- [Core types](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag/src/domain.ts): `packages/hybrid-rag/src/domain.ts`

### Document ingestion

- [Document loading](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-ingestion/src/loader.ts): `packages/hybrid-rag-ingestion/src/loader.ts`
- [Preprocessing](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-ingestion/src/preprocessor.ts): `packages/hybrid-rag-ingestion/src/preprocessor.ts`
- [Chunking engine](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-ingestion/src/chunking-engine.ts): `packages/hybrid-rag-ingestion/src/chunking-engine.ts`
- [Chunk strategies](https://github.com/reaatech/hybrid-rag/tree/main/packages/hybrid-rag-ingestion/src/chunking-strategies): `packages/hybrid-rag-ingestion/src/chunking-strategies`

### Hybrid retrieval

- [Embedding service](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-embedding/src/embedding.ts): `packages/hybrid-rag-embedding/src/embedding.ts`
- [Hybrid retriever](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/fusion/hybrid-retriever.ts): `packages/hybrid-rag-retrieval/src/fusion/hybrid-retriever.ts`
- [Vector search](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/vector-search.ts): `packages/hybrid-rag-retrieval/src/vector-search.ts`
- [BM25 search](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/bm25/search.ts): `packages/hybrid-rag-retrieval/src/bm25/search.ts`
- [BM25 tokenizer](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/bm25/tokenizer.ts): `packages/hybrid-rag-retrieval/src/bm25/tokenizer.ts`
- [Fusion and reranking](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/fusion/engine.ts): `packages/hybrid-rag-retrieval/src/fusion/engine.ts`
- [Cross-encoder reranker](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/reranker.ts): `packages/hybrid-rag-retrieval/src/reranker.ts`

### Vector storage

- [Store selection](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-retrieval/src/vector-store-factory.ts): `packages/hybrid-rag-retrieval/src/vector-store-factory.ts`
- [15 vector adapters](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-qdrant/src/qdrant-client.ts): `packages/hybrid-rag-qdrant/src/qdrant-client.ts`
- [Store migration](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-migration/src/migration.ts): `packages/hybrid-rag-migration/src/migration.ts`

### Evaluation and operations

- [Evaluation runner](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/runner.ts): `packages/hybrid-rag-evaluation/src/runner.ts`
- [Retrieval metrics](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/metrics/retrieval.ts): `packages/hybrid-rag-evaluation/src/metrics/retrieval.ts`
- [Ablation studies](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/ablation/runner.ts): `packages/hybrid-rag-evaluation/src/ablation/runner.ts`
- [Performance benchmarks](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-evaluation/src/benchmarking/db-benchmark.ts): `packages/hybrid-rag-evaluation/src/benchmarking/db-benchmark.ts`
- [Observability](https://github.com/reaatech/hybrid-rag/blob/main/packages/hybrid-rag-observability/src/logger.ts): `packages/hybrid-rag-observability/src/logger.ts`

### Other components

- **RAG user**

## Connections

- RAG user → CLI: runs commands (evidence: `README.md`)
- RAG user → MCP server: uses agent tools (evidence: `README.md`)
- RAG user → RAG pipeline: calls API (evidence: `README.md`)
- CLI → RAG pipeline: ingests and queries
- MCP server → RAG pipeline: provides RAG tools
- RAG pipeline → Chunking engine: chunks documents (evidence: `packages/hybrid-rag-pipeline/src/pipeline.ts`)
- RAG pipeline → Embedding service: generates embeddings (evidence: `packages/hybrid-rag-pipeline/src/pipeline.ts`)
- RAG pipeline → Hybrid retriever: runs retrieval (evidence: `packages/hybrid-rag-pipeline/src/pipeline.ts`)
- RAG pipeline → Store selection: creates store (evidence: `packages/hybrid-rag-pipeline/src/pipeline.ts`)
- Document loading → Preprocessing: prepares documents
- Chunking engine → Chunk strategies: dispatches strategy (evidence: `packages/hybrid-rag-ingestion/src/chunking-engine.ts`)
- Hybrid retriever → Vector search: searches vectors (evidence: `packages/hybrid-rag-retrieval/src/fusion/hybrid-retriever.ts`)
- Hybrid retriever → BM25 search: searches keywords (evidence: `packages/hybrid-rag-retrieval/src/fusion/hybrid-retriever.ts`)
- Hybrid retriever → Fusion and reranking: fuses results (evidence: `packages/hybrid-rag-retrieval/src/fusion/hybrid-retriever.ts`)
- BM25 search → BM25 tokenizer: tokenizes text
- Fusion and reranking → Cross-encoder reranker: reranks results (evidence: `packages/hybrid-rag-retrieval/src/fusion/engine.ts`)
- Vector search → Embedding service: embeds queries (evidence: `packages/hybrid-rag-retrieval/src/vector-search.ts`)
- Store selection → 15 vector adapters: selects provider
- Store migration → 15 vector adapters: moves vectors
- Evaluation runner → Retrieval metrics: computes scores
- Evaluation runner → RAG pipeline: evaluates queries
- Ablation studies → Evaluation runner: compares variants
- Performance benchmarks → 15 vector adapters: benchmarks latency
