# xbl2602/rag-redo architecture

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

- Interactive diagram: https://gitdiagram.com/xbl2602/rag-redo
- Repository: https://github.com/xbl2602/rag-redo

## Overview

RAG NAVIGATION builds a local, content-based map of note libraries so a person or AI assistant can locate a file and section without reading the whole collection. The principal workflow is library selection, extraction, chunking and indexing, followed by semantic and lexical retrieval, fusion, reranking and result delivery. The README also documents independent PDF page navigation, OCR, library summaries, note relations, duplicate detection and import/export. Unsampled plugin internals are represented at their exact implementation paths; relationships use README evidence where capabilities are documented but source calls were not excerpted.

Main entry points: [`core/pipeline.py`](https://github.com/xbl2602/rag-redo/blob/master/core/pipeline.py) (RAG pipeline), [`plugins/official-mcp-server/official_mcp_server/tools.py`](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-mcp-server/official_mcp_server/tools.py) (MCP tools), [`gui_main.py`](https://github.com/xbl2602/rag-redo/blob/master/gui_main.py) (Desktop app), [`core/cli.py`](https://github.com/xbl2602/rag-redo/blob/master/core/cli.py) (Command line)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_desktop["Desktop app<br/>[gui_main.py]"]
  node_mcp["MCP tools<br/>[tools.py]"]
  node_cli["Command line<br/>[cli.py]"]
end

subgraph group_index["Library indexing"]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_library["Library manager<br/>[plugin.py]"]
  node_extract["Document extraction<br/>[extract.py]"]
  node_ocr["OCR extraction<br/>[extract.py]"]
  node_chunk["Chunking<br/>[chunk.py]"]
  node_embed["Embedding<br/>[embed.py]"]
end

subgraph group_search["Search and navigation"]
  node_lexical["BM25 indexing<br/>[bm25.py]"]
  node_vector[("Vector store<br/>[store.py]")]
  node_fusion["Rank fusion<br/>[rrf.py]"]
  node_rerank["Reranking<br/>[rerank.py]"]
  node_visual["PDF page navigation<br/>[plugin.py]"]
end

subgraph group_plugins["Optional capabilities"]
  node_summary["Library summaries<br/>[plugin.py]"]
  node_relations["Note relations<br/>[note_relations.py]"]
  node_dedup["Duplicate detection<br/>[dedup.py]"]
  node_archive["Import / export<br/>[archive.py]"]
end

subgraph group_core["Runtime and state"]
  node_runtime["Plugin runtime<br/>[runtime.py]"]
  node_progress["Index workers<br/>[index_progress.py]"]
  node_cache["Conversion cache"]
end

node_person(("Person / AI"))

node_person -->|"opens"| node_desktop
node_person -->|"asks"| node_mcp
node_person -->|"runs"| node_cli
node_desktop -->|"uses"| node_pipeline
node_mcp -->|"calls"| node_pipeline
node_cli -->|"uses"| node_pipeline
node_pipeline -->|"selects files"| node_library
node_pipeline -->|"extracts text"| node_extract
node_pipeline -.->|"routes scans"| node_ocr
node_pipeline -->|"chunks text"| node_chunk
node_pipeline -->|"embeds chunks"| node_embed
node_pipeline -->|"indexes terms"| node_lexical
node_pipeline -->|"writes vectors"| node_vector
node_pipeline -->|"reports progress"| node_progress
node_pipeline -->|"uses cache"| node_cache
node_pipeline -.->|"builds page index"| node_visual
node_pipeline -->|"retrieves terms"| node_lexical
node_pipeline -->|"retrieves vectors"| node_vector
node_pipeline -->|"fuses ranks"| node_fusion
node_pipeline -->|"reranks results"| node_rerank
node_mcp -.->|"offers summaries"| node_summary
node_mcp -->|"offers links"| node_relations
node_mcp -.->|"offers duplicate check"| node_dedup
node_mcp -->|"offers archive transfer"| node_archive
node_desktop -.->|"shows page map"| node_visual
node_desktop -.->|"shows summaries"| node_summary
node_desktop -.->|"shows note links"| node_relations
node_runtime -->|"hosts plugins"| node_pipeline

click node_desktop "https://github.com/xbl2602/rag-redo/blob/master/gui_main.py"
click node_mcp "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-mcp-server/official_mcp_server/tools.py"
click node_cli "https://github.com/xbl2602/rag-redo/blob/master/core/cli.py"
click node_pipeline "https://github.com/xbl2602/rag-redo/blob/master/core/pipeline.py"
click node_library "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-library-manager/official_library_manager/plugin.py"
click node_extract "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-extractor-pdf-text/official_extractor_pdf_text/extract.py"
click node_ocr "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-ocr-mineru-cloud/official_ocr_mineru_cloud/extract.py"
click node_chunk "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-chunker/official_chunker/chunk.py"
click node_embed "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-embedder-bge-m3/official_embedder_bge_m3/embed.py"
click node_lexical "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-lexical-bm25/official_lexical_bm25/bm25.py"
click node_vector "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-vector-store-chroma/official_vector_store_chroma/store.py"
click node_fusion "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-fusion-rrf/official_fusion_rrf/rrf.py"
click node_rerank "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-reranker/official_reranker/rerank.py"
click node_visual "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-visual-wemm/official_visual_wemm/plugin.py"
click node_summary "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-library-summary/official_library_summary/plugin.py"
click node_relations "https://github.com/xbl2602/rag-redo/blob/master/core/note_relations.py"
click node_dedup "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-dedup/official_dedup/dedup.py"
click node_archive "https://github.com/xbl2602/rag-redo/blob/master/plugins/official-import-export/official_import_export/archive.py"
click node_runtime "https://github.com/xbl2602/rag-redo/blob/master/core/runtime.py"
click node_progress "https://github.com/xbl2602/rag-redo/blob/master/core/index_progress.py"
click node_cache "https://github.com/xbl2602/rag-redo/blob/master/core/conversion_cache.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_desktop,node_mcp,node_cli toneBlue
class node_pipeline,node_library,node_extract,node_ocr,node_chunk,node_embed toneAmber
class node_lexical,node_vector,node_fusion,node_rerank,node_visual toneMint
class node_summary,node_relations,node_dedup,node_archive toneRose
class node_runtime,node_progress,node_cache,node_person toneIndigo
```

## Components

### User entry points

- [Desktop app](https://github.com/xbl2602/rag-redo/blob/master/gui_main.py): `gui_main.py`
- [MCP tools](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-mcp-server/official_mcp_server/tools.py): `plugins/official-mcp-server/official_mcp_server/tools.py`
- [Command line](https://github.com/xbl2602/rag-redo/blob/master/core/cli.py): `core/cli.py`

### Library indexing

- [RAG pipeline](https://github.com/xbl2602/rag-redo/blob/master/core/pipeline.py): `core/pipeline.py`
- [Library manager](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-library-manager/official_library_manager/plugin.py): `plugins/official-library-manager/official_library_manager/plugin.py`
- [Document extraction](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-extractor-pdf-text/official_extractor_pdf_text/extract.py): `plugins/official-extractor-pdf-text/official_extractor_pdf_text/extract.py`
- [OCR extraction](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-ocr-mineru-cloud/official_ocr_mineru_cloud/extract.py): `plugins/official-ocr-mineru-cloud/official_ocr_mineru_cloud/extract.py`
- [Chunking](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-chunker/official_chunker/chunk.py): `plugins/official-chunker/official_chunker/chunk.py`
- [Embedding](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-embedder-bge-m3/official_embedder_bge_m3/embed.py): `plugins/official-embedder-bge-m3/official_embedder_bge_m3/embed.py`

### Search and navigation

- [BM25 indexing](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-lexical-bm25/official_lexical_bm25/bm25.py): `plugins/official-lexical-bm25/official_lexical_bm25/bm25.py`
- [Vector store](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-vector-store-chroma/official_vector_store_chroma/store.py): `plugins/official-vector-store-chroma/official_vector_store_chroma/store.py`
- [Rank fusion](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-fusion-rrf/official_fusion_rrf/rrf.py): `plugins/official-fusion-rrf/official_fusion_rrf/rrf.py`
- [Reranking](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-reranker/official_reranker/rerank.py): `plugins/official-reranker/official_reranker/rerank.py`
- [PDF page navigation](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-visual-wemm/official_visual_wemm/plugin.py): `plugins/official-visual-wemm/official_visual_wemm/plugin.py`

### Optional capabilities

- [Library summaries](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-library-summary/official_library_summary/plugin.py): `plugins/official-library-summary/official_library_summary/plugin.py`
- [Note relations](https://github.com/xbl2602/rag-redo/blob/master/core/note_relations.py): `core/note_relations.py`
- [Duplicate detection](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-dedup/official_dedup/dedup.py): `plugins/official-dedup/official_dedup/dedup.py`
- [Import / export](https://github.com/xbl2602/rag-redo/blob/master/plugins/official-import-export/official_import_export/archive.py): `plugins/official-import-export/official_import_export/archive.py`

### Runtime and state

- [Plugin runtime](https://github.com/xbl2602/rag-redo/blob/master/core/runtime.py): `core/runtime.py`
- [Index workers](https://github.com/xbl2602/rag-redo/blob/master/core/index_progress.py): `core/index_progress.py`
- [Conversion cache](https://github.com/xbl2602/rag-redo/blob/master/core/conversion_cache.py): `core/conversion_cache.py`

### Other components

- **Person / AI**

## Connections

- Person / AI → Desktop app: opens
- Person / AI → MCP tools: asks
- Person / AI → Command line: runs
- Desktop app → RAG pipeline: uses (evidence: `gui_main.py`)
- MCP tools → RAG pipeline: calls (evidence: `plugins/official-mcp-server/official_mcp_server/tools.py`)
- Command line → RAG pipeline: uses (evidence: `core/cli.py`)
- RAG pipeline → Library manager: selects files
- RAG pipeline → Document extraction: extracts text
- RAG pipeline → OCR extraction: routes scans
- RAG pipeline → Chunking: chunks text
- RAG pipeline → Embedding: embeds chunks
- RAG pipeline → BM25 indexing: indexes terms
- RAG pipeline → Vector store: writes vectors
- RAG pipeline → Index workers: reports progress (evidence: `core/pipeline.py`)
- RAG pipeline → Conversion cache: uses cache (evidence: `core/pipeline.py`)
- RAG pipeline → PDF page navigation: builds page index
- RAG pipeline → BM25 indexing: retrieves terms
- RAG pipeline → Vector store: retrieves vectors
- RAG pipeline → Rank fusion: fuses ranks
- RAG pipeline → Reranking: reranks results
- MCP tools → Library summaries: offers summaries
- MCP tools → Note relations: offers links (evidence: `plugins/official-mcp-server/official_mcp_server/tools.py`)
- MCP tools → Duplicate detection: offers duplicate check
- MCP tools → Import / export: offers archive transfer (evidence: `plugins/official-mcp-server/official_mcp_server/tools.py`)
- Desktop app → PDF page navigation: shows page map
- Desktop app → Library summaries: shows summaries
- Desktop app → Note relations: shows note links
- Plugin runtime → RAG pipeline: hosts plugins (evidence: `core/runtime.py`)