# kabitacodeforge/adaptive-rag-agent architecture

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

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

## Overview

1. **Two-user-facing entry points**
   - The repository is split into a **FastAPI backend** under `src/` and a **Streamlit frontend** under `streamlit_app/`.
   - Streamlit is the human interface for login/chat/document upload, while FastAPI exposes the actual RAG and upload endpoints that the UI calls through `streamlit_app/utils/api_client.py`.

2. **Backend application boundary**
   - `src/main.py` is the backend startup point and wires the API routes from `src/api/routes.py`.
   - This is the main service boundary: requests enter through HTTP, then move into the RAG pipeline, persistence layers, or LLM integrations depending on the route.

3. **Core request paths**
   - The backend exposes two primary flows:
     - `POST /rag/query` for conversational question answering
     - `POST /rag/documents/upload` for ingesting PDFs/TXTs into the retrieval index
   - Query traffic and document ingestion are separate pipelines, but they share configuration, logging, and storage backends.

4. **Adaptive RAG orchestration**
   - The central intelligence is in `src/rag/graph_builder.py` and `src/rag/nodes.py`, which define a **LangGraph-driven state machine**.
   - The graph coordinates query analysis, routing, retrieval, grading, rewriting, answer generation, and fallback paths.
   - This is the key architectural boundary between “request handling” and “agentic reasoning.”

5. **Routing logic and execution modes**
   - Queries are classified into three paths: **index**, **general**, or **search**.
   - `src/models/route_identifier.py` and the prompt definitions in `src/config/prompts.yaml` support this decisioning.
   - The index path uses document retrieval, general uses direct LLM answering, and search invokes external web search through the agent/tool layer.

6. **Retrieval and vector storage**
   - Document-based answering depends on `src/rag/retriever_setup.py` and `src/rag/document_upload.py`.
   - Uploaded documents are chunked, embedded, and stored in **Qdrant** as the vector database.
   - This retrieval subsystem is isolated from the chat logic so documents can be indexed independently of active conversations.

7. **LLM and agent layer**
   - `src/llms/openai.py` is the provider integration layer for OpenAI models.
   - `src/rag/reAct_agent.py` and the tool modules in `src/tools/` implement the agentic behavior, including ReAct-style tool use and helper functions for graph decisions.
   - The LLM layer is therefore not called directly by the UI; it is mediated by the graph and tool abstractions.

8. **Conversation memory and session state**
   - Chat history is modeled as persistent session state, not just ephemeral prompts.
   - `src/memory/chat_history_mongo.py` stores conversation history in **MongoDB** for persistence, while `src/memory/chathistory_in_memory.py` provides a fallback in-memory implementation.
   - This memory layer is the boundary between per-request processing and longer-lived conversational context.

9. **Data models and state contracts**
   - `src/models/` contains the shared schemas that keep backend components aligned:
     - `query_request.py` for incoming query payloads
     - `state.py` for graph state
     - `grade.py` and `verification_result.py` for retrieval/answer evaluation
   - These models define the data contracts passed between API, graph nodes, memory, and generation steps.

10. **Infrastructure and external dependencies**
   - The system depends on:
     - **OpenAI** for generation
     - **Qdrant** for vector search
     - **MongoDB** for session/chat persistence
     - **Tavily** for live web search
   - `src/config/settings.py`, `src/core/config.py`, and `src/db/mongo_client.py` centralize environment-driven setup, while `src/core/logger.py` handles observability.

11. **Frontend-to-backend flow**
   - The Streamlit app is a thin presentation layer: it collects user input, uploads files, and forwards requests to the backend API.
   - The backend returns structured responses, which Streamlit renders in the chat interface.
   - This keeps the UI stateless relative to the RAG pipeline; the session continuity lives in MongoDB-backed memory.

12. **Repository organization as architecture**
   - `src/api` = HTTP boundary
   - `src/rag` = orchestration and retrieval logic
   - `src/llms` = model provider integration
   - `src/memory` = conversation persistence
   - `src/db` = database clients
   - `src/models` = shared schemas/state
   - `streamlit_app` = user interface
   - The architecture is therefore a modular, backend-first RAG system with a separate frontend client and explicit storage/service boundaries.

Main entry points: [`src/api/routes.py`](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/api/routes.py) (API routes), [`src/rag/nodes.py`](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/nodes.py) (RAG nodes), [`src/rag/graph_builder.py`](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/graph_builder.py) (Graph builder), [`src/rag/reAct_agent.py`](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/reAct_agent.py) (ReAct agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Streamlit UI"]
  node_streamlit_home["Home UI<br/>streamlit entry<br/>[home.py]"]
  node_streamlit_chat["Chat page<br/>streamlit page<br/>[chat.py]"]
  node_api_client["API client<br/>http client<br/>[api_client.py]"]
end

subgraph group_backend["FastAPI backend"]
  node_main_app["App start<br/>backend entry<br/>[main.py]"]
  node_api_routes["API routes<br/>http routes<br/>[routes.py]"]
end

subgraph group_rag["RAG engine"]
  node_graph_builder{{"Graph builder<br/>langgraph orchestration<br/>[graph_builder.py]"}}
  node_rag_nodes["RAG nodes<br/>state nodes<br/>[nodes.py]"]
  node_document_upload["Doc upload<br/>ingestion pipeline<br/>[document_upload.py]"]
  node_retriever_setup["Retriever<br/>vector retrieval<br/>[retriever_setup.py]"]
  node_re2agent{{"ReAct agent<br/>tool agent<br/>[reAct_agent.py]"}}
  node_tools["Tools<br/>toolkit<br/>[common_tools.py]"]
end

subgraph group_data["State and storage"]
  node_route_identifier["Route ID<br/>routing model"]
  node_prompts["Prompts<br/>prompt config<br/>[prompts.yaml]"]
  node_openai["OpenAI<br/>llm provider<br/>[openai.py]"]
  node_chat_memory[("Chat memory<br/>persistent session store")]
  node_mongo_client[("Mongo client<br/>db client<br/>[mongo_client.py]")]
  node_state_models["State models<br/>shared schemas<br/>[state.py]"]
  node_settings["Settings<br/>env config<br/>[settings.py]"]
  node_qdrant[("Qdrant<br/>vector db")]
  node_tavily(("Tavily<br/>web search"))
end

node_streamlit_home -->|"uses"| node_api_client
node_streamlit_chat -->|"calls"| node_api_client
node_api_client -->|"HTTP"| node_api_routes
node_main_app -->|"mounts"| node_api_routes
node_api_routes -->|"query path"| node_graph_builder
node_api_routes -->|"upload path"| node_document_upload
node_graph_builder -->|"assembles"| node_rag_nodes
node_rag_nodes -->|"routes"| node_route_identifier
node_rag_nodes -->|"guides"| node_prompts
node_rag_nodes -->|"retrieves"| node_retriever_setup
node_rag_nodes -->|"delegates"| node_re2agent
node_rag_nodes -->|"generates"| node_openai
node_re2agent -->|"uses"| node_tools
node_re2agent -->|"searches"| node_tavily
node_document_upload -->|"indexes"| node_qdrant
node_retriever_setup -->|"reads"| node_qdrant
node_api_routes -->|"loads"| node_chat_memory
node_chat_memory -->|"persists"| node_mongo_client
node_api_routes -->|"validates"| node_state_models
node_graph_builder -->|"shares"| node_state_models
node_main_app -->|"configures"| node_settings
node_api_routes -->|"reads"| node_settings

click node_streamlit_home "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/streamlit_app/home.py"
click node_streamlit_chat "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/streamlit_app/pages/chat.py"
click node_api_client "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/streamlit_app/utils/api_client.py"
click node_main_app "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/main.py"
click node_api_routes "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/api/routes.py"
click node_graph_builder "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/graph_builder.py"
click node_rag_nodes "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/nodes.py"
click node_route_identifier "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/models/route_identifier.py"
click node_prompts "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/config/prompts.yaml"
click node_document_upload "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/document_upload.py"
click node_retriever_setup "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/retriever_setup.py"
click node_re2agent "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/reAct_agent.py"
click node_tools "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/tools/common_tools.py"
click node_openai "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/llms/openai.py"
click node_chat_memory "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/memory/chat_history_mongo.py"
click node_mongo_client "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/db/mongo_client.py"
click node_state_models "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/models/state.py"
click node_settings "https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/config/settings.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_streamlit_home,node_streamlit_chat,node_api_client toneBlue
class node_main_app,node_api_routes toneAmber
class node_graph_builder,node_rag_nodes,node_document_upload,node_retriever_setup,node_re2agent,node_tools toneMint
class node_route_identifier,node_prompts,node_openai,node_chat_memory,node_mongo_client,node_state_models,node_settings,node_qdrant,node_tavily toneRose
```

## Components

### Streamlit UI

Human-facing interface for chat, login, and document upload.

- [Home UI](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/streamlit_app/home.py): streamlit entry · Streamlit landing and app shell. · `streamlit_app/home.py`
- [Chat page](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/streamlit_app/pages/chat.py): streamlit page · Chat and upload user workflow. · `streamlit_app/pages/chat.py`
- [API client](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/streamlit_app/utils/api_client.py): http client · Frontend bridge to backend endpoints. · `streamlit_app/utils/api_client.py`

### FastAPI backend

HTTP service boundary for query handling and document ingestion.

- [App start](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/main.py): backend entry · Backend startup and application wiring. · `src/main.py`
- [API routes](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/api/routes.py): http routes · RAG and upload HTTP endpoints. · `src/api/routes.py`

### RAG engine

Adaptive orchestration, retrieval, and agent execution.

- [Graph builder](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/graph_builder.py): langgraph orchestration · Builds the adaptive reasoning state machine. · `src/rag/graph_builder.py`
- [RAG nodes](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/nodes.py): state nodes · Query analysis, routing, retrieval, grading, rewrite, and answer steps. · `src/rag/nodes.py`
- [Doc upload](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/document_upload.py): ingestion pipeline · Chunking, embedding, and indexing for uploaded files. · `src/rag/document_upload.py`
- [Retriever](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/retriever_setup.py): vector retrieval · Document retrieval wiring for indexed knowledge. · `src/rag/retriever_setup.py`
- [ReAct agent](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/rag/reAct_agent.py): tool agent · Agentic search and tool-using execution. · `src/rag/reAct_agent.py`
- [Tools](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/tools/common_tools.py): toolkit · Shared helper and graph tool functions. · `src/tools/common_tools.py`

### State and storage

Shared schemas plus persistence and external data services.

- [Route ID](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/models/route_identifier.py): routing model · Classifies requests into index, general, or search paths. · `src/models/route_identifier.py`
- [Prompts](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/config/prompts.yaml): prompt config · Prompt templates and routing instructions. · `src/config/prompts.yaml`
- [OpenAI](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/llms/openai.py): llm provider · Model integration for generation and reasoning. · `src/llms/openai.py`
- [Chat memory](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/memory/chat_history_mongo.py): persistent session store · MongoDB-backed conversation history. · `src/memory/chat_history_mongo.py`
- [Mongo client](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/db/mongo_client.py): db client · MongoDB connection setup. · `src/db/mongo_client.py`
- [State models](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/models/state.py): shared schemas · Request, graph state, grading, and verification contracts. · `src/models/state.py`
- [Settings](https://github.com/kabitacodeforge/adaptive-rag-agent/blob/main/src/config/settings.py): env config · Environment-driven application configuration. · `src/config/settings.py`
- **Qdrant**: vector db · Vector store for indexed documents.
- **Tavily**: web search · External search service used by search flows.

## Connections

- Home UI → API client: uses · UI triggers backend requests through the client.
- Chat page → API client: calls · Chat and upload actions are forwarded to the API.
- API client → API routes: HTTP · Frontend communicates with backend endpoints.
- App start → API routes: mounts · Application startup wires route handlers.
- API routes → Graph builder: query path · Query requests enter the adaptive RAG graph.
- API routes → Doc upload: upload path · Document ingestion requests enter the indexing pipeline.
- Graph builder → RAG nodes: assembles · Graph builder composes the execution nodes.
- RAG nodes → Route ID: routes · Classifies requests into execution modes.
- RAG nodes → Prompts: guides · Prompt templates shape analysis and generation.
- RAG nodes → Retriever: retrieves · Index-path nodes query the retrieval layer.
- RAG nodes → ReAct agent: delegates · Search-path nodes hand off to the agent layer.
- RAG nodes → OpenAI: generates · LLM-backed answer generation and rewriting.
- ReAct agent → Tools: uses · Agent relies on tool helpers and graph utilities.
- ReAct agent → Tavily: searches · Web search is performed through the external search service.
- Doc upload → Qdrant: indexes · Embedded chunks are stored in the vector database.
- Retriever → Qdrant: reads · Retrieval queries the vector store.
- API routes → Chat memory: loads · Conversation context is fetched and updated per request.
- Chat memory → Mongo client: persists · MongoDB-backed memory uses the database client.
- API routes → State models: validates · API payloads and graph state are shaped by shared schemas.
- Graph builder → State models: shares · Graph execution depends on common state contracts.
- App start → Settings: configures · Startup uses environment-driven settings.
- API routes → Settings: reads · Routes use shared runtime configuration.