# sugeerth/production-rag architecture

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

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

## Overview

Production RAG serves private-document question answering: users upload or re-index documents, then ask questions and receive grounded answers with citations. The ingestion path parses and chunks documents before embedding and indexing; the query path rewrites questions, performs hybrid retrieval and reranking, applies safety checks, and generates cited answers. The app coordinates these stages and exposes document management, feedback, and monitoring. README capabilities guide the architecture where implementation excerpts are incomplete; links to unsampled subsystems are limited to documented behavior.

Main entry points: [`app.py`](https://github.com/sugeerth/production-rag/blob/main/app.py) (FastAPI app), [`rag/indexing.py`](https://github.com/sugeerth/production-rag/blob/main/rag/indexing.py) (Index and search), [`rag/generation.py`](https://github.com/sugeerth/production-rag/blob/main/rag/generation.py) (Context and generation), [`static/app.js`](https://github.com/sugeerth/production-rag/blob/main/static/app.js) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ui["Web UI<br/>[app.js]"]
  node_api["FastAPI app<br/>[app.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_corpus["Document corpus"]
  node_ingestion["Parse and chunk<br/>[ingestion.py]"]
  node_embedding["Embeddings<br/>[embeddings.py]"]
  node_indexing["Index and search<br/>[indexing.py]"]
  node_vectorstore[("ChromaDB")]
  node_bm25[("BM25 index<br/>[indexing.py]")]
end

subgraph group_query["Question answering"]
  node_retrieval["Rewrite and rerank<br/>[retrieval.py]"]
  node_generation["Context and generation<br/>[generation.py]"]
  node_guardrails["Safety checks<br/>[guardrails.py]"]
end

subgraph group_ops["Monitoring and state"]
  node_evaluation["Query evaluation<br/>[evaluation.py]"]
  node_logs[("Query log store<br/>[evaluation.py]")]
  node_dashboard["Monitoring dashboard<br/>[app.js]"]
end

node_user(("User"))
node_embedmodel["Sentence-Transformers"]
node_ollama["Ollama LLM"]

node_user -->|"asks or uploads"| node_ui
node_ui -->|"sends requests"| node_api
node_api -->|"stores uploads"| node_corpus
node_api -->|"ingests documents"| node_ingestion
node_corpus -->|"reads files"| node_ingestion
node_ingestion -->|"returns chunks"| node_api
node_api -->|"indexes chunks"| node_indexing
node_indexing -->|"embeds chunks"| node_embedding
node_embedding -->|"encodes text"| node_embedmodel
node_indexing -->|"upserts and queries"| node_vectorstore
node_indexing -->|"builds and searches"| node_bm25
node_api -->|"retrieves answers"| node_retrieval
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"hybrid search"| node_indexing
node_retrieval -->|"returns ranked chunks"| node_api
node_api -->|"generates answer"| node_generation
node_generation -->|"checks safety"| node_guardrails
node_generation -->|"requests completion"| node_ollama
node_ollama -->|"returns answer"| node_generation
node_generation -->|"returns citations"| node_api
node_api -->|"logs query"| node_evaluation
node_evaluation -->|"persists logs"| node_logs
node_api -->|"gets metrics and logs"| node_evaluation
node_api -->|"gets index stats"| node_indexing
node_ui -->|"renders monitoring"| node_dashboard
node_dashboard -->|"requests stats and logs"| node_api
node_ui -->|"submits feedback"| node_api
node_api -->|"records feedback"| node_evaluation

click node_ui "https://github.com/sugeerth/production-rag/blob/main/static/app.js"
click node_api "https://github.com/sugeerth/production-rag/blob/main/app.py"
click node_corpus "https://github.com/sugeerth/production-rag/tree/main/documents"
click node_ingestion "https://github.com/sugeerth/production-rag/blob/main/rag/ingestion.py"
click node_embedding "https://github.com/sugeerth/production-rag/blob/main/rag/embeddings.py"
click node_indexing "https://github.com/sugeerth/production-rag/blob/main/rag/indexing.py"
click node_bm25 "https://github.com/sugeerth/production-rag/blob/main/rag/indexing.py"
click node_retrieval "https://github.com/sugeerth/production-rag/blob/main/rag/retrieval.py"
click node_generation "https://github.com/sugeerth/production-rag/blob/main/rag/generation.py"
click node_guardrails "https://github.com/sugeerth/production-rag/blob/main/rag/guardrails.py"
click node_evaluation "https://github.com/sugeerth/production-rag/blob/main/rag/evaluation.py"
click node_logs "https://github.com/sugeerth/production-rag/blob/main/rag/evaluation.py"
click node_dashboard "https://github.com/sugeerth/production-rag/blob/main/static/app.js"

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_ui,node_api,node_user toneBlue
class node_corpus,node_ingestion,node_embedding,node_indexing,node_vectorstore,node_bm25 toneAmber
class node_retrieval,node_generation,node_guardrails toneMint
class node_evaluation,node_logs,node_dashboard toneRose
class node_embedmodel,node_ollama toneIndigo
```

## Components

### User interface

- [Web UI](https://github.com/sugeerth/production-rag/blob/main/static/app.js): `static/app.js`
- [FastAPI app](https://github.com/sugeerth/production-rag/blob/main/app.py): `app.py`

### Document ingestion

- [Document corpus](https://github.com/sugeerth/production-rag/tree/main/documents): `documents`
- [Parse and chunk](https://github.com/sugeerth/production-rag/blob/main/rag/ingestion.py): `rag/ingestion.py`
- [Embeddings](https://github.com/sugeerth/production-rag/blob/main/rag/embeddings.py): `rag/embeddings.py`
- [Index and search](https://github.com/sugeerth/production-rag/blob/main/rag/indexing.py): `rag/indexing.py`
- **ChromaDB**
- [BM25 index](https://github.com/sugeerth/production-rag/blob/main/rag/indexing.py): `rag/indexing.py`

### Question answering

- [Rewrite and rerank](https://github.com/sugeerth/production-rag/blob/main/rag/retrieval.py): `rag/retrieval.py`
- [Context and generation](https://github.com/sugeerth/production-rag/blob/main/rag/generation.py): `rag/generation.py`
- [Safety checks](https://github.com/sugeerth/production-rag/blob/main/rag/guardrails.py): `rag/guardrails.py`

### Monitoring and state

- [Query evaluation](https://github.com/sugeerth/production-rag/blob/main/rag/evaluation.py): `rag/evaluation.py`
- [Query log store](https://github.com/sugeerth/production-rag/blob/main/rag/evaluation.py): `rag/evaluation.py`
- [Monitoring dashboard](https://github.com/sugeerth/production-rag/blob/main/static/app.js): `static/app.js`

### Other components

- **User**
- **Sentence-Transformers**
- **Ollama LLM**

## Connections

- User → Web UI: asks or uploads
- Web UI → FastAPI app: sends requests
- FastAPI app → Document corpus: stores uploads
- FastAPI app → Parse and chunk: ingests documents
- Document corpus → Parse and chunk: reads files
- Parse and chunk → FastAPI app: returns chunks
- FastAPI app → Index and search: indexes chunks
- Index and search → Embeddings: embeds chunks
- Embeddings → Sentence-Transformers: encodes text
- Index and search → ChromaDB: upserts and queries
- Index and search → BM25 index: builds and searches
- FastAPI app → Rewrite and rerank: retrieves answers
- Rewrite and rerank → Embeddings: embeds query
- Rewrite and rerank → Index and search: hybrid search
- Rewrite and rerank → FastAPI app: returns ranked chunks
- FastAPI app → Context and generation: generates answer
- Context and generation → Safety checks: checks safety
- Context and generation → Ollama LLM: requests completion
- Ollama LLM → Context and generation: returns answer
- Context and generation → FastAPI app: returns citations
- FastAPI app → Query evaluation: logs query
- Query evaluation → Query log store: persists logs
- FastAPI app → Query evaluation: gets metrics and logs
- FastAPI app → Index and search: gets index stats
- Web UI → Monitoring dashboard: renders monitoring
- Monitoring dashboard → FastAPI app: requests stats and logs
- Web UI → FastAPI app: submits feedback
- FastAPI app → Query evaluation: records feedback