# dharamveer007/adaptive-rag architecture

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

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

## Overview

Adaptive RAG is a document-aware chatbot with both React and Streamlit interfaces, backed by a FastAPI service. Users authenticate, create or select a session, optionally upload documents, and submit questions; the API persists conversation history and invokes a LangGraph workflow that routes among document retrieval, general answers, and web search before returning a response. The graph also preserves session history, document indexing, grading, rewriting, and answer generation as distinct responsibilities. Source excerpts show the API and workflow wiring; some UI and pipeline details are supported only by the README or source index.

Main entry points: [`src/api/routes.py`](https://github.com/dharamveer007/adaptive-rag/blob/main/src/api/routes.py) (RAG endpoints), [`src/rag/graph_builder.py`](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py) (Query classification), [`frontend/src/App.jsx`](https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/App.jsx) (React application), [`frontend/src/api/client.js`](https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/api/client.js) (React API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_react_app["React application<br/>[App.jsx]"]
  node_chat_ui["Chat interface<br/>[ChatArea.jsx]"]
  node_upload_ui["Upload dialog<br/>[UploadModal.jsx]"]
  node_login_ui["Login page<br/>[LoginPage.jsx]"]
  node_streamlit_ui["Streamlit chat<br/>[chat.py]"]
  node_react_client["React API client<br/>[client.js]"]
  node_streamlit_client["Streamlit API client<br/>[api_client.py]"]
end

subgraph group_service["API and sessions"]
  node_fastapi["FastAPI service<br/>[main.py]"]
  node_api_routes["RAG endpoints<br/>[routes.py]"]
  node_auth["API authentication<br/>[security.py]"]
  node_chat_history["Session history"]
end

subgraph group_workflow["Adaptive RAG workflow"]
  node_graph["Workflow orchestration<br/>[graph_builder.py]"]
  node_query_routing["Query classification<br/>[graph_builder.py]"]
  node_retrieval_agent["Retrieval agent<br/>[reAct_agent.py]"]
  node_grading_rewrite["Grade and rewrite<br/>[graph_builder.py]"]
  node_answer_generation["Answer generation<br/>[graph_builder.py]"]
  node_web_search["Web search<br/>[graph_builder.py]"]
  node_general_model["General LLM<br/>[graph_builder.py]"]
end

subgraph group_knowledge["Knowledge and integrations"]
  node_mongo[("MongoDB<br/>[mongo_client.py]")]
  node_upload_processor["Document processing<br/>[document_upload.py]"]
  node_vector_index[("Vector retrieval<br/>[retriever_setup.py]")]
  node_llm["Groq language model<br/>[openai.py]"]
end

node_end_user(("Chat user"))

node_end_user -->|"uses"| node_react_app
node_end_user -->|"uses"| node_streamlit_ui
node_react_app -->|"renders"| node_chat_ui
node_react_app -->|"opens"| node_upload_ui
node_react_app -->|"shows"| node_login_ui
node_react_app -->|"calls"| node_react_client
node_chat_ui -->|"calls"| node_react_client
node_upload_ui -->|"uploads through"| node_react_client
node_login_ui -->|"authenticates through"| node_react_client
node_react_client -->|"calls"| node_api_routes
node_streamlit_ui -->|"calls"| node_streamlit_client
node_streamlit_client -->|"calls"| node_api_routes
node_streamlit_client -.->|"calls auth service"| node_auth
node_fastapi -->|"registers"| node_api_routes
node_api_routes -->|"authenticates"| node_auth
node_api_routes -->|"reads and writes"| node_chat_history
node_chat_history -->|"persists in"| node_mongo
node_api_routes -->|"queries sessions"| node_mongo
node_api_routes -->|"invokes"| node_graph
node_api_routes -->|"dispatches upload"| node_upload_processor
node_upload_processor -->|"indexes chunks"| node_vector_index
node_graph -->|"starts at"| node_query_routing
node_query_routing -->|"classifies with retrieval"| node_vector_index
node_query_routing -->|"routes index queries"| node_retrieval_agent
node_retrieval_agent -->|"retrieves from"| node_vector_index
node_retrieval_agent -->|"returns results for grading"| node_grading_rewrite
node_grading_rewrite -->|"rewrites and retries"| node_retrieval_agent
node_grading_rewrite -->|"routes relevant results"| node_answer_generation
node_query_routing -->|"routes general queries"| node_general_model
node_query_routing -->|"routes search queries"| node_web_search
node_web_search -->|"passes search results"| node_answer_generation
node_general_model -->|"generates with"| node_llm
node_query_routing -->|"classifies with"| node_llm
node_grading_rewrite -->|"grades and rewrites with"| node_llm
node_answer_generation -->|"generates with"| node_llm

click node_react_app "https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/App.jsx"
click node_chat_ui "https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/components/ChatArea.jsx"
click node_upload_ui "https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/components/UploadModal.jsx"
click node_login_ui "https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/pages/LoginPage.jsx"
click node_streamlit_ui "https://github.com/dharamveer007/adaptive-rag/blob/main/streamlit_app/pages/chat.py"
click node_react_client "https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/api/client.js"
click node_streamlit_client "https://github.com/dharamveer007/adaptive-rag/blob/main/streamlit_app/utils/api_client.py"
click node_fastapi "https://github.com/dharamveer007/adaptive-rag/blob/main/src/main.py"
click node_api_routes "https://github.com/dharamveer007/adaptive-rag/blob/main/src/api/routes.py"
click node_auth "https://github.com/dharamveer007/adaptive-rag/blob/main/src/api/security.py"
click node_chat_history "https://github.com/dharamveer007/adaptive-rag/blob/main/src/memory/chat_history_mongo.py"
click node_mongo "https://github.com/dharamveer007/adaptive-rag/blob/main/src/db/mongo_client.py"
click node_upload_processor "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/document_upload.py"
click node_vector_index "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/retriever_setup.py"
click node_graph "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py"
click node_query_routing "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py"
click node_retrieval_agent "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/reAct_agent.py"
click node_grading_rewrite "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py"
click node_answer_generation "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py"
click node_web_search "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py"
click node_general_model "https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py"
click node_llm "https://github.com/dharamveer007/adaptive-rag/blob/main/src/llms/openai.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_react_app,node_chat_ui,node_upload_ui,node_login_ui,node_streamlit_ui,node_react_client,node_streamlit_client,node_end_user toneBlue
class node_fastapi,node_api_routes,node_auth,node_chat_history toneAmber
class node_graph,node_query_routing,node_retrieval_agent,node_grading_rewrite,node_answer_generation,node_web_search,node_general_model toneMint
class node_mongo,node_upload_processor,node_vector_index,node_llm toneRose
```

## Components

### User interfaces

- [React application](https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat interface](https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/components/ChatArea.jsx): `frontend/src/components/ChatArea.jsx`
- [Upload dialog](https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/components/UploadModal.jsx): `frontend/src/components/UploadModal.jsx`
- [Login page](https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/pages/LoginPage.jsx): `frontend/src/pages/LoginPage.jsx`
- [Streamlit chat](https://github.com/dharamveer007/adaptive-rag/blob/main/streamlit_app/pages/chat.py): `streamlit_app/pages/chat.py`
- [React API client](https://github.com/dharamveer007/adaptive-rag/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Streamlit API client](https://github.com/dharamveer007/adaptive-rag/blob/main/streamlit_app/utils/api_client.py): `streamlit_app/utils/api_client.py`

### API and sessions

- [FastAPI service](https://github.com/dharamveer007/adaptive-rag/blob/main/src/main.py): `src/main.py`
- [RAG endpoints](https://github.com/dharamveer007/adaptive-rag/blob/main/src/api/routes.py): `src/api/routes.py`
- [API authentication](https://github.com/dharamveer007/adaptive-rag/blob/main/src/api/security.py): `src/api/security.py`
- [Session history](https://github.com/dharamveer007/adaptive-rag/blob/main/src/memory/chat_history_mongo.py): `src/memory/chat_history_mongo.py`

### Adaptive RAG workflow

- [Workflow orchestration](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py): `src/rag/graph_builder.py`
- [Query classification](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py): `src/rag/graph_builder.py`
- [Retrieval agent](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/reAct_agent.py): `src/rag/reAct_agent.py`
- [Grade and rewrite](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py): `src/rag/graph_builder.py`
- [Answer generation](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py): `src/rag/graph_builder.py`
- [Web search](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py): `src/rag/graph_builder.py`
- [General LLM](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/graph_builder.py): `src/rag/graph_builder.py`

### Knowledge and integrations

- [MongoDB](https://github.com/dharamveer007/adaptive-rag/blob/main/src/db/mongo_client.py): `src/db/mongo_client.py`
- [Document processing](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/document_upload.py): `src/rag/document_upload.py`
- [Vector retrieval](https://github.com/dharamveer007/adaptive-rag/blob/main/src/rag/retriever_setup.py): `src/rag/retriever_setup.py`
- [Groq language model](https://github.com/dharamveer007/adaptive-rag/blob/main/src/llms/openai.py): `src/llms/openai.py`

### Other components

- **Chat user**

## Connections

- Chat user → React application: uses (evidence: `README.md`)
- Chat user → Streamlit chat: uses (evidence: `README.md`)
- React application → Chat interface: renders (evidence: `frontend/src/App.jsx`)
- React application → Upload dialog: opens (evidence: `frontend/src/App.jsx`)
- React application → Login page: shows (evidence: `frontend/src/App.jsx`)
- React application → React API client: calls (evidence: `frontend/src/App.jsx`)
- Chat interface → React API client: calls (evidence: `frontend/src/components/ChatArea.jsx`)
- Upload dialog → React API client: uploads through (evidence: `frontend/src/components/UploadModal.jsx`)
- Login page → React API client: authenticates through (evidence: `frontend/src/pages/LoginPage.jsx`)
- React API client → RAG endpoints: calls (evidence: `frontend/src/api/client.js`)
- Streamlit chat → Streamlit API client: calls (evidence: `streamlit_app/pages/chat.py`)
- Streamlit API client → RAG endpoints: calls (evidence: `streamlit_app/utils/api_client.py`)
- Streamlit API client → API authentication: calls auth service
- FastAPI service → RAG endpoints: registers (evidence: `src/main.py`)
- RAG endpoints → API authentication: authenticates (evidence: `src/api/routes.py`)
- RAG endpoints → Session history: reads and writes (evidence: `src/api/routes.py`)
- Session history → MongoDB: persists in (evidence: `src/memory/chat_history_mongo.py`)
- RAG endpoints → MongoDB: queries sessions (evidence: `src/api/routes.py`)
- RAG endpoints → Workflow orchestration: invokes (evidence: `src/api/routes.py`)
- RAG endpoints → Document processing: dispatches upload (evidence: `src/api/routes.py`)
- Document processing → Vector retrieval: indexes chunks (evidence: `src/rag/document_upload.py`)
- Workflow orchestration → Query classification: starts at (evidence: `src/rag/graph_builder.py`)
- Query classification → Vector retrieval: classifies with retrieval (evidence: `src/rag/graph_builder.py`)
- Query classification → Retrieval agent: routes index queries (evidence: `src/rag/graph_builder.py`)
- Retrieval agent → Vector retrieval: retrieves from (evidence: `src/rag/reAct_agent.py`)
- Retrieval agent → Grade and rewrite: returns results for grading (evidence: `src/rag/graph_builder.py`)
- Grade and rewrite → Retrieval agent: rewrites and retries (evidence: `src/rag/graph_builder.py`)
- Grade and rewrite → Answer generation: routes relevant results (evidence: `src/rag/graph_builder.py`)
- Query classification → General LLM: routes general queries (evidence: `src/rag/graph_builder.py`)
- Query classification → Web search: routes search queries (evidence: `src/rag/graph_builder.py`)
- Web search → Answer generation: passes search results (evidence: `src/rag/graph_builder.py`)
- General LLM → Groq language model: generates with (evidence: `src/rag/graph_builder.py`)
- Query classification → Groq language model: classifies with (evidence: `src/rag/graph_builder.py`)
- Grade and rewrite → Groq language model: grades and rewrites with (evidence: `src/rag/graph_builder.py`)
- Answer generation → Groq language model: generates with (evidence: `src/rag/graph_builder.py`)
