# nvkdzvcl/rag architecture

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

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

## Overview

Self-RAG is a document-grounded question-answering application with a React interface and FastAPI backend. Users upload PDF, DOCX, text, or Markdown documents; the backend parses, cleans, chunks, and indexes them, then answers filtered queries in standard, advanced, or compare mode with citations and optional SSE progress. Standard and advanced workflows preserve their distinct retrieval and answer-verification stages; compare runs both. The README documents dense/BM25 retrieval and local index persistence. Some subsystem links reflect documented capabilities because their implementation was not sampled.

Main entry points: [`app/indexing/builder.py`](https://github.com/nvkdzvcl/rag/blob/main/app/indexing/builder.py) (Index builder), [`app/workflows/standard.py`](https://github.com/nvkdzvcl/rag/blob/main/app/workflows/standard.py) (Standard workflow), [`app/workflows/advanced_pipeline.py`](https://github.com/nvkdzvcl/rag/blob/main/app/workflows/advanced_pipeline.py) (Advanced stages), [`app/main.py`](https://github.com/nvkdzvcl/rag/blob/main/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_frontend["React app<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_ingestion_hook["Document controls"]
end

subgraph group_api["API and services"]
  node_main["FastAPI app<br/>[main.py]"]
  node_query_routes["Query routes<br/>[query.py]"]
  node_document_routes["Document routes<br/>[documents.py]"]
  node_query_service["Query service<br/>[query_service.py]"]
  node_document_service["Document service"]
  node_runtime["Service runtime<br/>[runtime.py]"]
end

subgraph group_documents["Document processing"]
  node_directory_ingestor["Document loaders"]
  node_chunker["Chunking<br/>[chunker.py]"]
end

subgraph group_answering["Retrieval and answering"]
  node_runner["Workflow runner<br/>[runner.py]"]
  node_standard["Standard workflow<br/>[standard.py]"]
  node_advanced["Advanced workflow<br/>[advanced.py]"]
  node_compare["Compare workflow<br/>[compare.py]"]
  node_advanced_pipeline["Advanced stages"]
  node_retrieval["Hybrid retrieval<br/>[hybrid.py]"]
  node_reranker["Reranking<br/>[reranker.py]"]
  node_context["Context selection"]
  node_generation["Answer generation<br/>[baseline.py]"]
  node_citations["Citation handling<br/>[citations.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_state["Index state"]
  node_index_builder["Index builder<br/>[builder.py]"]
  node_vector_index[("Vector index<br/>[vector_index.py]")]
  node_bm25_index[("BM25 index<br/>[bm25_index.py]")]
  node_persistence["Index persistence<br/>[persistence.py]"]
end

node_user(("User"))
node_llm_service(("LLM endpoint"))

node_user -->|"uses"| node_frontend
node_frontend -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_main
node_ingestion_hook -->|"uploads and manages"| node_api_client
node_main -->|"builds services"| node_runtime
node_main -->|"mounts routes"| node_query_routes
node_query_routes -->|"executes query"| node_query_service
node_query_service -->|"dispatches"| node_runner
node_runner -->|"runs standard"| node_standard
node_runner -->|"runs advanced"| node_advanced
node_runner -->|"runs both"| node_compare
node_compare -->|"runs standard"| node_standard
node_compare -->|"runs advanced"| node_advanced
node_standard -->|"retrieves"| node_retrieval
node_standard -->|"reranks"| node_reranker
node_standard -->|"selects context"| node_context
node_standard -->|"generates answer"| node_generation
node_advanced -->|"executes stages"| node_advanced_pipeline
node_advanced_pipeline -->|"retrieves"| node_retrieval
node_advanced_pipeline -->|"reranks"| node_reranker
node_advanced_pipeline -->|"selects context"| node_context
node_advanced_pipeline -->|"drafts and refines"| node_generation
node_generation -->|"completes prompts"| node_llm
node_llm -.->|"sends completion"| node_llm_service
node_generation -->|"adds citations"| node_citations
node_main -->|"mounts routes"| node_document_routes
node_document_routes -->|"manages documents"| node_document_service
node_document_service -->|"loads documents"| node_directory_ingestor
node_directory_ingestor -->|"produces text for"| node_chunker
node_document_service -->|"builds index"| node_index_builder
node_index_builder -->|"indexes vectors"| node_vector_index
node_index_builder -->|"indexes terms"| node_bm25_index
node_index_builder -->|"consumes documents"| node_directory_ingestor
node_index_builder -->|"chunks content"| node_chunker
node_retrieval -->|"searches dense"| node_vector_index
node_retrieval -->|"searches sparse"| node_bm25_index
node_index_builder -->|"persists index"| node_persistence

click node_frontend "https://github.com/nvkdzvcl/rag/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/nvkdzvcl/rag/blob/main/frontend/src/api/client.ts"
click node_ingestion_hook "https://github.com/nvkdzvcl/rag/blob/main/frontend/src/hooks/use-document-ingestion.ts"
click node_main "https://github.com/nvkdzvcl/rag/blob/main/app/main.py"
click node_query_routes "https://github.com/nvkdzvcl/rag/blob/main/app/api/routes/query.py"
click node_document_routes "https://github.com/nvkdzvcl/rag/blob/main/app/api/routes/documents.py"
click node_query_service "https://github.com/nvkdzvcl/rag/blob/main/app/services/query_service.py"
click node_document_service "https://github.com/nvkdzvcl/rag/blob/main/app/services/document_service.py"
click node_runtime "https://github.com/nvkdzvcl/rag/blob/main/app/services/runtime.py"
click node_runner "https://github.com/nvkdzvcl/rag/blob/main/app/workflows/runner.py"
click node_standard "https://github.com/nvkdzvcl/rag/blob/main/app/workflows/standard.py"
click node_advanced "https://github.com/nvkdzvcl/rag/blob/main/app/workflows/advanced.py"
click node_compare "https://github.com/nvkdzvcl/rag/blob/main/app/workflows/compare.py"
click node_advanced_pipeline "https://github.com/nvkdzvcl/rag/blob/main/app/workflows/advanced_pipeline.py"
click node_retrieval "https://github.com/nvkdzvcl/rag/blob/main/app/retrieval/hybrid.py"
click node_reranker "https://github.com/nvkdzvcl/rag/blob/main/app/retrieval/reranker.py"
click node_context "https://github.com/nvkdzvcl/rag/blob/main/app/retrieval/context_selector.py"
click node_generation "https://github.com/nvkdzvcl/rag/blob/main/app/generation/baseline.py"
click node_citations "https://github.com/nvkdzvcl/rag/blob/main/app/generation/citations.py"
click node_llm "https://github.com/nvkdzvcl/rag/blob/main/app/generation/llm_client.py"
click node_directory_ingestor "https://github.com/nvkdzvcl/rag/blob/main/app/ingestion/directory_ingestor.py"
click node_chunker "https://github.com/nvkdzvcl/rag/blob/main/app/ingestion/chunker.py"
click node_index_builder "https://github.com/nvkdzvcl/rag/blob/main/app/indexing/builder.py"
click node_vector_index "https://github.com/nvkdzvcl/rag/blob/main/app/indexing/vector_index.py"
click node_bm25_index "https://github.com/nvkdzvcl/rag/blob/main/app/indexing/bm25_index.py"
click node_persistence "https://github.com/nvkdzvcl/rag/blob/main/app/indexing/persistence.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_frontend,node_api_client,node_ingestion_hook,node_user toneBlue
class node_main,node_query_routes,node_document_routes,node_query_service,node_document_service,node_runtime toneAmber
class node_directory_ingestor,node_chunker toneMint
class node_runner,node_standard,node_advanced,node_compare,node_advanced_pipeline,node_retrieval,node_reranker,node_context,node_generation,node_citations,node_llm toneRose
class node_index_builder,node_vector_index,node_bm25_index,node_persistence,node_llm_service toneIndigo
```

## Components

### User interface

- [React app](https://github.com/nvkdzvcl/rag/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/nvkdzvcl/rag/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Document controls](https://github.com/nvkdzvcl/rag/blob/main/frontend/src/hooks/use-document-ingestion.ts): `frontend/src/hooks/use-document-ingestion.ts`

### API and services

- [FastAPI app](https://github.com/nvkdzvcl/rag/blob/main/app/main.py): `app/main.py`
- [Query routes](https://github.com/nvkdzvcl/rag/blob/main/app/api/routes/query.py): `app/api/routes/query.py`
- [Document routes](https://github.com/nvkdzvcl/rag/blob/main/app/api/routes/documents.py): `app/api/routes/documents.py`
- [Query service](https://github.com/nvkdzvcl/rag/blob/main/app/services/query_service.py): `app/services/query_service.py`
- [Document service](https://github.com/nvkdzvcl/rag/blob/main/app/services/document_service.py): `app/services/document_service.py`
- [Service runtime](https://github.com/nvkdzvcl/rag/blob/main/app/services/runtime.py): `app/services/runtime.py`

### Document processing

- [Document loaders](https://github.com/nvkdzvcl/rag/blob/main/app/ingestion/directory_ingestor.py): `app/ingestion/directory_ingestor.py`
- [Chunking](https://github.com/nvkdzvcl/rag/blob/main/app/ingestion/chunker.py): `app/ingestion/chunker.py`

### Retrieval and answering

- [Workflow runner](https://github.com/nvkdzvcl/rag/blob/main/app/workflows/runner.py): `app/workflows/runner.py`
- [Standard workflow](https://github.com/nvkdzvcl/rag/blob/main/app/workflows/standard.py): `app/workflows/standard.py`
- [Advanced workflow](https://github.com/nvkdzvcl/rag/blob/main/app/workflows/advanced.py): `app/workflows/advanced.py`
- [Compare workflow](https://github.com/nvkdzvcl/rag/blob/main/app/workflows/compare.py): `app/workflows/compare.py`
- [Advanced stages](https://github.com/nvkdzvcl/rag/blob/main/app/workflows/advanced_pipeline.py): `app/workflows/advanced_pipeline.py`
- [Hybrid retrieval](https://github.com/nvkdzvcl/rag/blob/main/app/retrieval/hybrid.py): `app/retrieval/hybrid.py`
- [Reranking](https://github.com/nvkdzvcl/rag/blob/main/app/retrieval/reranker.py): `app/retrieval/reranker.py`
- [Context selection](https://github.com/nvkdzvcl/rag/blob/main/app/retrieval/context_selector.py): `app/retrieval/context_selector.py`
- [Answer generation](https://github.com/nvkdzvcl/rag/blob/main/app/generation/baseline.py): `app/generation/baseline.py`
- [Citation handling](https://github.com/nvkdzvcl/rag/blob/main/app/generation/citations.py): `app/generation/citations.py`
- [LLM client](https://github.com/nvkdzvcl/rag/blob/main/app/generation/llm_client.py): `app/generation/llm_client.py`

### Index state

- [Index builder](https://github.com/nvkdzvcl/rag/blob/main/app/indexing/builder.py): `app/indexing/builder.py`
- [Vector index](https://github.com/nvkdzvcl/rag/blob/main/app/indexing/vector_index.py): `app/indexing/vector_index.py`
- [BM25 index](https://github.com/nvkdzvcl/rag/blob/main/app/indexing/bm25_index.py): `app/indexing/bm25_index.py`
- [Index persistence](https://github.com/nvkdzvcl/rag/blob/main/app/indexing/persistence.py): `app/indexing/persistence.py`

### Other components

- **User**
- **LLM endpoint**

## Connections

- User → React app: uses
- React app → API client: requests
- API client → FastAPI app: calls API
- Document controls → API client: uploads and manages
- FastAPI app → Service runtime: builds services
- FastAPI app → Query routes: mounts routes
- Query routes → Query service: executes query
- Query service → Workflow runner: dispatches
- Workflow runner → Standard workflow: runs standard
- Workflow runner → Advanced workflow: runs advanced
- Workflow runner → Compare workflow: runs both
- Compare workflow → Standard workflow: runs standard
- Compare workflow → Advanced workflow: runs advanced
- Standard workflow → Hybrid retrieval: retrieves
- Standard workflow → Reranking: reranks
- Standard workflow → Context selection: selects context
- Standard workflow → Answer generation: generates answer
- Advanced workflow → Advanced stages: executes stages
- Advanced stages → Hybrid retrieval: retrieves
- Advanced stages → Reranking: reranks
- Advanced stages → Context selection: selects context
- Advanced stages → Answer generation: drafts and refines
- Answer generation → LLM client: completes prompts
- LLM client → LLM endpoint: sends completion
- Answer generation → Citation handling: adds citations
- FastAPI app → Document routes: mounts routes
- Document routes → Document service: manages documents
- Document service → Document loaders: loads documents
- Document loaders → Chunking: produces text for
- Document service → Index builder: builds index
- Index builder → Vector index: indexes vectors
- Index builder → BM25 index: indexes terms
- Index builder → Document loaders: consumes documents
- Index builder → Chunking: chunks content
- Hybrid retrieval → Vector index: searches dense
- Hybrid retrieval → BM25 index: searches sparse
- Index builder → Index persistence: persists index