# prabhakaranvijay/prod-rag architecture

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

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

## Overview

Prod-RAG is a FastAPI RAG backend. Users ingest local files or URLs for indexing, then ask questions answered from retrieved and reranked document chunks; document listing/deletion and health/readiness checks are also supported. The graph shows API ownership, ingestion stages, retrieval, generation, and the Chroma-backed index. README documents query rewriting and Ragas evaluation; evaluation is shown as a separate capability. Edges follow excerpted calls or explicit README statements; unsampled routing details are omitted.

Main entry points: [`app/services/rag_service.py`](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/services/rag_service.py) (RAG service), [`app/main.py`](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/main.py) (FastAPI app), [`app/retrieval/retriever.py`](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/retriever.py) (Search orchestrator), [`app/ingestion/pipeline.py`](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/pipeline.py) (Ingestion pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Service API"]
  node_main["FastAPI app<br/>[main.py]"]
  node_chat["Chat routes<br/>[chat.py]"]
  node_documents["Document routes<br/>[documents.py]"]
  node_health["Health probes<br/>[health.py]"]
  node_service["RAG service<br/>[rag_service.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_loader["Document loading<br/>[loader.py]"]
  node_metadata["Metadata enrichment<br/>[metadata.py]"]
  node_chunker["Document chunking<br/>[chunker.py]"]
end

subgraph group_retrieval["Search and ranking"]
  node_retriever["Search orchestrator<br/>[retriever.py]"]
  node_hybrid["Hybrid search<br/>[hybrid_search.py]"]
  node_vectorsearch["Vector search<br/>[vector_search.py]"]
  node_bm25["BM25 search<br/>[bm25.py]"]
  node_rerank["Cross-encoder reranker<br/>[bge_reranker.py]"]
end

subgraph group_generation["Answer generation"]
  node_chain["RAG chain<br/>[rag_chain.py]"]
  node_llm["Groq generation<br/>[groq.py]"]
end

subgraph group_support["Index and evaluation"]
  node_chroma[("Chroma index<br/>[chroma.py]")]
  node_embeddings["BGE embeddings"]
  node_evaluation["Ragas evaluation<br/>[ragas_eval.py]"]
  node_evalrunner["Evaluation runner<br/>[runner.py]"]
end

node_user(("API client"))
node_groqservice(("Groq API"))

node_user -->|"sends requests"| node_main
node_main -->|"mounts routes"| node_chat
node_main -->|"mounts routes"| node_documents
node_main -->|"mounts routes"| node_health
node_chat -->|"calls"| node_service
node_documents -->|"calls"| node_service
node_main -->|"initializes"| node_service
node_service -->|"runs ingestion"| node_pipeline
node_pipeline -->|"loads documents"| node_loader
node_pipeline -->|"enriches metadata"| node_metadata
node_pipeline -->|"splits documents"| node_chunker
node_service -->|"indexes chunks"| node_retriever
node_service -->|"asks question"| node_chain
node_chain -->|"searches query"| node_retriever
node_retriever -->|"dispatches search"| node_hybrid
node_retriever -->|"dispatches vector"| node_vectorsearch
node_retriever -->|"dispatches keyword"| node_bm25
node_hybrid -->|"combines results"| node_vectorsearch
node_hybrid -->|"combines results"| node_bm25
node_hybrid -->|"reranks candidates"| node_rerank
node_vectorsearch -->|"queries index"| node_chroma
node_vectorsearch -->|"writes and lists"| node_chroma
node_chroma -->|"creates embeddings"| node_embeddings
node_chain -->|"generates answer"| node_llm
node_llm -.->|"requests completion"| node_groqservice
node_evalrunner -->|"runs pipeline"| node_service
node_evalrunner -->|"scores results"| node_evaluation

click node_main "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/main.py"
click node_chat "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/api/routes/chat.py"
click node_documents "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/api/routes/documents.py"
click node_health "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/api/routes/health.py"
click node_service "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/services/rag_service.py"
click node_pipeline "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/pipeline.py"
click node_loader "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/loader.py"
click node_metadata "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/metadata.py"
click node_chunker "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/chunker.py"
click node_chain "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/chains/rag_chain.py"
click node_llm "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/llm/groq.py"
click node_retriever "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/retriever.py"
click node_hybrid "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/hybrid_search.py"
click node_vectorsearch "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/vector_search.py"
click node_bm25 "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/bm25.py"
click node_rerank "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/reranking/bge_reranker.py"
click node_chroma "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/vectorstore/chroma.py"
click node_embeddings "https://github.com/prabhakaranvijay/prod-rag/blob/main/app/embeddings/embedding_factory.py"
click node_evaluation "https://github.com/prabhakaranvijay/prod-rag/blob/main/evaluation/ragas_eval.py"
click node_evalrunner "https://github.com/prabhakaranvijay/prod-rag/blob/main/evaluation/runner.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_main,node_chat,node_documents,node_health,node_service,node_user toneBlue
class node_pipeline,node_loader,node_metadata,node_chunker toneAmber
class node_retriever,node_hybrid,node_vectorsearch,node_bm25,node_rerank,node_groqservice toneMint
class node_chain,node_llm toneRose
class node_chroma,node_embeddings,node_evaluation,node_evalrunner toneIndigo
```

## Components

### Service API

- [FastAPI app](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/main.py): `app/main.py`
- [Chat routes](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/api/routes/chat.py): `app/api/routes/chat.py`
- [Document routes](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/api/routes/documents.py): `app/api/routes/documents.py`
- [Health probes](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/api/routes/health.py): `app/api/routes/health.py`
- [RAG service](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/services/rag_service.py): `app/services/rag_service.py`

### Document ingestion

- [Ingestion pipeline](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/pipeline.py): `app/ingestion/pipeline.py`
- [Document loading](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/loader.py): `app/ingestion/loader.py`
- [Metadata enrichment](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/metadata.py): `app/ingestion/metadata.py`
- [Document chunking](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/ingestion/chunker.py): `app/ingestion/chunker.py`

### Search and ranking

- [Search orchestrator](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/retriever.py): `app/retrieval/retriever.py`
- [Hybrid search](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/hybrid_search.py): `app/retrieval/hybrid_search.py`
- [Vector search](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/vector_search.py): `app/retrieval/vector_search.py`
- [BM25 search](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/retrieval/bm25.py): `app/retrieval/bm25.py`
- [Cross-encoder reranker](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/reranking/bge_reranker.py): `app/reranking/bge_reranker.py`

### Answer generation

- [RAG chain](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/chains/rag_chain.py): `app/chains/rag_chain.py`
- [Groq generation](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/llm/groq.py): `app/llm/groq.py`

### Index and evaluation

- [Chroma index](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/vectorstore/chroma.py): `app/vectorstore/chroma.py`
- [BGE embeddings](https://github.com/prabhakaranvijay/prod-rag/blob/main/app/embeddings/embedding_factory.py): `app/embeddings/embedding_factory.py`
- [Ragas evaluation](https://github.com/prabhakaranvijay/prod-rag/blob/main/evaluation/ragas_eval.py): `evaluation/ragas_eval.py`
- [Evaluation runner](https://github.com/prabhakaranvijay/prod-rag/blob/main/evaluation/runner.py): `evaluation/runner.py`

### Other components

- **API client**
- **Groq API**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → Chat routes: mounts routes (evidence: `app/main.py`)
- FastAPI app → Document routes: mounts routes (evidence: `app/main.py`)
- FastAPI app → Health probes: mounts routes (evidence: `app/main.py`)
- Chat routes → RAG service: calls (evidence: `app/api/routes/chat.py`)
- Document routes → RAG service: calls (evidence: `app/api/routes/documents.py`)
- FastAPI app → RAG service: initializes (evidence: `app/main.py`)
- RAG service → Ingestion pipeline: runs ingestion (evidence: `app/services/rag_service.py`)
- Ingestion pipeline → Document loading: loads documents (evidence: `app/ingestion/pipeline.py`)
- Ingestion pipeline → Metadata enrichment: enriches metadata (evidence: `app/ingestion/pipeline.py`)
- Ingestion pipeline → Document chunking: splits documents (evidence: `app/ingestion/pipeline.py`)
- RAG service → Search orchestrator: indexes chunks (evidence: `app/services/rag_service.py`)
- RAG service → RAG chain: asks question (evidence: `app/services/rag_service.py`)
- RAG chain → Search orchestrator: searches query (evidence: `app/chains/rag_chain.py`)
- Search orchestrator → Hybrid search: dispatches search (evidence: `app/retrieval/retriever.py`)
- Search orchestrator → Vector search: dispatches vector (evidence: `app/retrieval/retriever.py`)
- Search orchestrator → BM25 search: dispatches keyword (evidence: `app/retrieval/retriever.py`)
- Hybrid search → Vector search: combines results (evidence: `app/retrieval/hybrid_search.py`)
- Hybrid search → BM25 search: combines results (evidence: `app/retrieval/hybrid_search.py`)
- Hybrid search → Cross-encoder reranker: reranks candidates (evidence: `app/retrieval/hybrid_search.py`)
- Vector search → Chroma index: queries index (evidence: `app/retrieval/vector_search.py`)
- Vector search → Chroma index: writes and lists (evidence: `app/retrieval/vector_search.py`)
- Chroma index → BGE embeddings: creates embeddings (evidence: `app/vectorstore/chroma.py`)
- RAG chain → Groq generation: generates answer (evidence: `app/chains/rag_chain.py`)
- Groq generation → Groq API: requests completion
- Evaluation runner → RAG service: runs pipeline (evidence: `evaluation/runner.py`)
- Evaluation runner → Ragas evaluation: scores results (evidence: `evaluation/runner.py`)
