# shaadclt/agentic-adaptive-rag architecture

> Architecture diagram of the GitHub repository shaadclt/agentic-adaptive-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/shaadclt/agentic-adaptive-rag
- Repository: https://github.com/shaadclt/agentic-adaptive-rag

## Overview

Agentic Adaptive RAG accepts questions and uploaded documents, routes each question between local retrieval and web search, grades evidence and answers, then returns a protected response with sources. Document ingestion, evaluation, and observability are supporting product workflows. The README documents the frontend/backend capabilities; sampled backend files and the SOURCE INDEX support several implementation links. Some frontend-to-API wiring and unsampled graph details are documented but not directly visible in source excerpts.

Main entry points: [`backend/graph/graph.py`](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/graph.py) (LangGraph Workflow), [`backend/api.py`](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/api.py) (HTTP API), [`backend/retrieval.py`](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/retrieval.py) (Local Retrieval), [`backend/model.py`](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/model.py) (LLM and Embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web_ui["Chat UI<br/>[page.tsx]"]
  node_eval_ui["Evaluation UI<br/>[page.tsx]"]
  node_obs_ui["Observability UI<br/>[page.tsx]"]
  node_api["HTTP API<br/>[api.py]"]
end

subgraph group_knowledge["Knowledge Base"]
  node_ingestion["Document Ingestion<br/>[ingestion.py]"]
  node_vectorstore[("Chroma Vector Store<br/>[ingestion.py]")]
  node_retrieval["Local Retrieval<br/>[retrieval.py]"]
  node_sources["Source Extraction<br/>[sources.py]"]
end

subgraph group_agent["Agent Workflow"]
  node_graph["LangGraph Workflow<br/>[graph.py]"]
  node_router["Query Router<br/>[router.py]"]
  node_retrieve_node["Retrieve Node<br/>[retrieve.py]"]
  node_retrieval_grade["Retrieval Grader"]
  node_web_search["Web Search<br/>[web_search.py]"]
  node_generation["Answer Generation<br/>[generation.py]"]
  node_answer_grade["Answer Graders<br/>[answer_grader.py]"]
  node_context["Evidence Context<br/>[context.py]"]
end

subgraph group_safety["Safety and Models"]
  node_security["Input Security<br/>[security.py]"]
  node_content_guard["Content Guard<br/>[content_guard.py]"]
  node_output_guard["Output Security<br/>[output_guard.py]"]
  node_security_config["Security Rules<br/>[security_config.py]"]
  node_models["LLM and Embeddings<br/>[model.py]"]
end

subgraph group_insight["Evaluation and Observability"]
  node_evaluation["Evaluation Tracker<br/>[evaluation.py]"]
  node_observability["Run Observability<br/>[observability.py]"]
end

node_user(("User"))
node_web_service["Web Search Service"]

node_user -.->|"asks or uploads"| node_web_ui
node_web_ui -.->|"sends requests"| node_api
node_api -->|"invokes"| node_graph
node_api -->|"manages documents"| node_ingestion
node_ingestion -->|"writes and lists"| node_vectorstore
node_retrieval -->|"searches"| node_vectorstore
node_graph -->|"retrieves routing context"| node_retrieval
node_graph -->|"checks requests"| node_security
node_graph -->|"routes questions"| node_router
node_graph -->|"dispatches retrieval"| node_retrieve_node
node_retrieve_node -->|"invokes retriever"| node_retrieval
node_graph -->|"grades retrieved documents"| node_retrieval_grade
node_graph -->|"dispatches fallback"| node_web_search
node_web_search -.->|"searches web"| node_web_service
node_graph -->|"generates answers"| node_generation
node_graph -->|"validates answers"| node_answer_grade
node_graph -->|"formats evidence"| node_context
node_context -->|"wraps untrusted text"| node_content_guard
node_graph -->|"protects response"| node_output_guard
node_security -->|"uses rules"| node_security_config
node_content_guard -->|"uses patterns"| node_security_config
node_output_guard -->|"uses limits"| node_security_config
node_router -->|"uses LLM"| node_models
node_generation -->|"uses LLM"| node_models
node_retrieval -->|"uses embeddings"| node_models
node_ingestion -->|"uses embeddings"| node_models
node_api -->|"extracts sources"| node_sources
node_graph -.->|"records run results"| node_evaluation
node_api -->|"serves evaluation"| node_evaluation
node_api -->|"serves run data"| node_observability
node_eval_ui -.->|"loads evaluation"| node_api
node_obs_ui -.->|"loads observability"| node_api
node_user -.->|"reviews results"| node_eval_ui
node_user -.->|"reviews runs"| node_obs_ui

click node_web_ui "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/frontend/src/app/page.tsx"
click node_eval_ui "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/frontend/src/app/evaluation/page.tsx"
click node_obs_ui "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/frontend/src/app/observability/page.tsx"
click node_api "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/api.py"
click node_ingestion "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/ingestion.py"
click node_vectorstore "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/ingestion.py"
click node_retrieval "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/retrieval.py"
click node_sources "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/sources.py"
click node_graph "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/graph.py"
click node_router "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/chains/router.py"
click node_retrieve_node "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/nodes/retrieve.py"
click node_retrieval_grade "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/chains/retrieval_grader.py"
click node_web_search "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/nodes/web_search.py"
click node_generation "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/chains/generation.py"
click node_answer_grade "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/chains/answer_grader.py"
click node_context "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/context.py"
click node_security "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/nodes/security.py"
click node_content_guard "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/security/content_guard.py"
click node_output_guard "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/security/output_guard.py"
click node_security_config "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/security/security_config.py"
click node_models "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/model.py"
click node_evaluation "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/evaluation.py"
click node_observability "https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/observability.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_web_ui,node_eval_ui,node_obs_ui,node_api,node_user toneBlue
class node_ingestion,node_vectorstore,node_retrieval,node_sources toneAmber
class node_graph,node_router,node_retrieve_node,node_retrieval_grade,node_web_search,node_generation,node_answer_grade,node_context toneMint
class node_security,node_content_guard,node_output_guard,node_security_config,node_models toneRose
class node_evaluation,node_observability,node_web_service toneIndigo
```

## Components

### User Experience

- [Chat UI](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Evaluation UI](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/frontend/src/app/evaluation/page.tsx): `frontend/src/app/evaluation/page.tsx`
- [Observability UI](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/frontend/src/app/observability/page.tsx): `frontend/src/app/observability/page.tsx`
- [HTTP API](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/api.py): `backend/api.py`

### Knowledge Base

- [Document Ingestion](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/ingestion.py): `backend/ingestion.py`
- [Chroma Vector Store](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/ingestion.py): `backend/ingestion.py`
- [Local Retrieval](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/retrieval.py): `backend/retrieval.py`
- [Source Extraction](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/sources.py): `backend/sources.py`

### Agent Workflow

- [LangGraph Workflow](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/graph.py): `backend/graph/graph.py`
- [Query Router](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/chains/router.py): `backend/graph/chains/router.py`
- [Retrieve Node](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/nodes/retrieve.py): `backend/graph/nodes/retrieve.py`
- [Retrieval Grader](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/chains/retrieval_grader.py): `backend/graph/chains/retrieval_grader.py`
- [Web Search](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/nodes/web_search.py): `backend/graph/nodes/web_search.py`
- [Answer Generation](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/chains/generation.py): `backend/graph/chains/generation.py`
- [Answer Graders](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/chains/answer_grader.py): `backend/graph/chains/answer_grader.py`
- [Evidence Context](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/context.py): `backend/graph/context.py`

### Safety and Models

- [Input Security](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/graph/nodes/security.py): `backend/graph/nodes/security.py`
- [Content Guard](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/security/content_guard.py): `backend/security/content_guard.py`
- [Output Security](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/security/output_guard.py): `backend/security/output_guard.py`
- [Security Rules](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/security/security_config.py): `backend/security/security_config.py`
- [LLM and Embeddings](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/model.py): `backend/model.py`

### Evaluation and Observability

- [Evaluation Tracker](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/evaluation.py): `backend/evaluation.py`
- [Run Observability](https://github.com/shaadclt/agentic-adaptive-rag/blob/main/backend/observability.py): `backend/observability.py`

### Other components

- **User**
- **Web Search Service**

## Connections

- User → Chat UI: asks or uploads (evidence: `README.md`)
- Chat UI → HTTP API: sends requests (evidence: `README.md`)
- HTTP API → LangGraph Workflow: invokes (evidence: `backend/api.py`)
- HTTP API → Document Ingestion: manages documents (evidence: `backend/api.py`)
- Document Ingestion → Chroma Vector Store: writes and lists (evidence: `backend/ingestion.py`)
- Local Retrieval → Chroma Vector Store: searches (evidence: `backend/retrieval.py`)
- LangGraph Workflow → Local Retrieval: retrieves routing context (evidence: `backend/graph/graph.py`)
- LangGraph Workflow → Input Security: checks requests (evidence: `backend/graph/graph.py`)
- LangGraph Workflow → Query Router: routes questions (evidence: `backend/graph/graph.py`)
- LangGraph Workflow → Retrieve Node: dispatches retrieval (evidence: `backend/graph/graph.py`)
- Retrieve Node → Local Retrieval: invokes retriever (evidence: `backend/graph/nodes/retrieve.py`)
- LangGraph Workflow → Retrieval Grader: grades retrieved documents (evidence: `backend/graph/graph.py`)
- LangGraph Workflow → Web Search: dispatches fallback (evidence: `backend/graph/graph.py`)
- Web Search → Web Search Service: searches web (evidence: `README.md`)
- LangGraph Workflow → Answer Generation: generates answers (evidence: `backend/graph/graph.py`)
- LangGraph Workflow → Answer Graders: validates answers (evidence: `backend/graph/graph.py`)
- LangGraph Workflow → Evidence Context: formats evidence (evidence: `backend/graph/graph.py`)
- Evidence Context → Content Guard: wraps untrusted text (evidence: `backend/graph/context.py`)
- LangGraph Workflow → Output Security: protects response (evidence: `backend/graph/graph.py`)
- Input Security → Security Rules: uses rules
- Content Guard → Security Rules: uses patterns (evidence: `backend/security/content_guard.py`)
- Output Security → Security Rules: uses limits (evidence: `backend/security/output_guard.py`)
- Query Router → LLM and Embeddings: uses LLM (evidence: `backend/graph/chains/router.py`)
- Answer Generation → LLM and Embeddings: uses LLM (evidence: `backend/graph/chains/generation.py`)
- Local Retrieval → LLM and Embeddings: uses embeddings (evidence: `backend/retrieval.py`)
- Document Ingestion → LLM and Embeddings: uses embeddings (evidence: `backend/ingestion.py`)
- HTTP API → Source Extraction: extracts sources (evidence: `backend/api.py`)
- LangGraph Workflow → Evaluation Tracker: records run results (evidence: `README.md`)
- HTTP API → Evaluation Tracker: serves evaluation (evidence: `backend/api.py`)
- HTTP API → Run Observability: serves run data (evidence: `backend/api.py`)
- Evaluation UI → HTTP API: loads evaluation (evidence: `README.md`)
- Observability UI → HTTP API: loads observability (evidence: `README.md`)
- User → Evaluation UI: reviews results (evidence: `README.md`)
- User → Observability UI: reviews runs (evidence: `README.md`)
