# ahamed-safnas/agentic-rag architecture

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

- Interactive diagram: https://gitdiagram.com/ahamed-safnas/agentic-rag
- Repository: https://github.com/ahamed-safnas/agentic-rag

## Overview

This is an enterprise document RAG application. Users submit questions through the Streamlit UI or API; the API applies guardrails, runs a stateful LangGraph planner/retriever/responder workflow, and returns an answer with sources and reasoning. A separate ingestion path parses, chunks, embeds, and indexes local documents. The README also documents evaluation, memory, caching, rate limiting, and observability capabilities. Relationships for the main workflow are supported by excerpts or README statements; unsampled integrations are shown only where documented.

Main entry points: [`app/main.py`](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/main.py) (FastAPI API), [`app/agents/graph.py`](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/graph.py) (Graph orchestration), [`app/ingestion/processor.py`](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/ingestion/processor.py) (Ingestion processor), [`evals/pipeline.py`](https://github.com/ahamed-safnas/agentic-rag/blob/dev/evals/pipeline.py) (Live eval pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["API and experience"]
  node_ui["Chat UI<br/>[app.py]"]
  node_api["FastAPI API<br/>[main.py]"]
  node_guardrails["Guardrails<br/>[rails.py]"]
end

subgraph group_agent["Agent workflow"]
  node_agent_graph["Graph orchestration<br/>[graph.py]"]
  node_agent_state["Agent state<br/>[state.py]"]
  node_planner["Query planner<br/>[planner.py]"]
  node_retriever["Document retriever<br/>[retriever.py]"]
  node_responder["Answer responder<br/>[responder.py]"]
end

subgraph group_knowledge["Knowledge ingestion and search"]
  node_ingestion["Ingestion processor<br/>[processor.py]"]
  node_loaders["Document loaders"]
  node_chunker["Text chunker<br/>[splitter.py]"]
  node_embeddings["Embedding service<br/>[embedding.py]"]
  node_qdrant["Vector search<br/>[qdrant_service.py]"]
  node_ranker["Semantic reranker<br/>[ranking_service.py]"]
end

subgraph group_platform["State and operations"]
  node_cache[("Response cache<br/>[cache.py]")]
  node_gateway["LLM gateway client<br/>[client.py]"]
  node_memory[("Conversation checkpoint<br/>[graph.py]")]
  node_metrics["Metrics endpoint<br/>[main.py]"]
  node_health["Health checks<br/>[health.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_pipeline["Live eval pipeline<br/>[pipeline.py]"]
  node_eval_metrics["RAG evaluation metrics<br/>[metrics.py]"]
  node_eval_guardrails["Guardrails evaluation<br/>[guardrails_eval.py]"]
end

node_user(("User"))
node_vector_db[("Qdrant")]
node_jina_embed["Jina embeddings API"]
node_jina_rank["Jina reranker API"]
node_redis[("Redis rate limiting")]

node_user -->|"asks question"| node_ui
node_ui -->|"submits query"| node_api
node_api -->|"checks input"| node_guardrails
node_api -->|"checks cache"| node_cache
node_api -->|"runs pipeline"| node_agent_graph
node_agent_graph -->|"dispatches"| node_planner
node_agent_graph -->|"routes technical"| node_retriever
node_agent_graph -->|"routes conversational"| node_responder
node_agent_graph -->|"uses state"| node_agent_state
node_planner -->|"requests LLM"| node_gateway
node_responder -->|"requests LLM"| node_gateway
node_guardrails -->|"requests LLM"| node_gateway
node_retriever -->|"searches"| node_qdrant
node_retriever -->|"reranks results"| node_ranker
node_qdrant -->|"embeds query"| node_embeddings
node_qdrant -->|"queries vectors"| node_vector_db
node_ranker -->|"reranks documents"| node_jina_rank
node_embeddings -->|"embeds texts"| node_jina_embed
node_ingestion -->|"parses files"| node_loaders
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"embeds chunks"| node_embeddings
node_ingestion -->|"upserts vectors"| node_vector_db
node_agent_graph -->|"checkpoints state"| node_memory
node_api -->|"limits requests"| node_redis
node_api -->|"exposes metrics"| node_metrics
node_api -->|"includes health routes"| node_health
node_eval_pipeline -->|"submits live queries"| node_api
node_eval_pipeline -.->|"evaluates results"| node_eval_metrics
node_eval_pipeline -.->|"evaluates safety"| node_eval_guardrails

click node_ui "https://github.com/ahamed-safnas/agentic-rag/blob/dev/ui/app.py"
click node_api "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/main.py"
click node_guardrails "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/guardrails/rails.py"
click node_cache "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/services/cache.py"
click node_agent_graph "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/graph.py"
click node_agent_state "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/state.py"
click node_planner "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/nodes/planner.py"
click node_retriever "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/nodes/retriever.py"
click node_responder "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/nodes/responder.py"
click node_gateway "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/gateway/client.py"
click node_ingestion "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/ingestion/processor.py"
click node_loaders "https://github.com/ahamed-safnas/agentic-rag/tree/dev/app/ingestion/loaders"
click node_chunker "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/ingestion/chunking/splitter.py"
click node_embeddings "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/services/retrieval/embedding.py"
click node_qdrant "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/services/retrieval/qdrant_service.py"
click node_ranker "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/services/retrieval/ranking_service.py"
click node_memory "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/graph.py"
click node_metrics "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/main.py"
click node_health "https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/health.py"
click node_eval_pipeline "https://github.com/ahamed-safnas/agentic-rag/blob/dev/evals/pipeline.py"
click node_eval_metrics "https://github.com/ahamed-safnas/agentic-rag/blob/dev/evals/metrics.py"
click node_eval_guardrails "https://github.com/ahamed-safnas/agentic-rag/blob/dev/evals/guardrails_eval.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_ui,node_api,node_guardrails,node_user toneBlue
class node_agent_graph,node_agent_state,node_planner,node_retriever,node_responder,node_vector_db,node_redis toneAmber
class node_ingestion,node_loaders,node_chunker,node_embeddings,node_qdrant,node_ranker,node_jina_embed,node_jina_rank toneMint
class node_cache,node_gateway,node_memory,node_metrics,node_health toneRose
class node_eval_pipeline,node_eval_metrics,node_eval_guardrails toneIndigo
```

## Components

### API and experience

- [Chat UI](https://github.com/ahamed-safnas/agentic-rag/blob/dev/ui/app.py): `ui/app.py`
- [FastAPI API](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/main.py): `app/main.py`
- [Guardrails](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/guardrails/rails.py): `app/guardrails/rails.py`

### Agent workflow

- [Graph orchestration](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/graph.py): `app/agents/graph.py`
- [Agent state](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/state.py): `app/agents/state.py`
- [Query planner](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/nodes/planner.py): `app/agents/nodes/planner.py`
- [Document retriever](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/nodes/retriever.py): `app/agents/nodes/retriever.py`
- [Answer responder](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/nodes/responder.py): `app/agents/nodes/responder.py`

### Knowledge ingestion and search

- [Ingestion processor](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/ingestion/processor.py): `app/ingestion/processor.py`
- [Document loaders](https://github.com/ahamed-safnas/agentic-rag/tree/dev/app/ingestion/loaders): `app/ingestion/loaders`
- [Text chunker](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/ingestion/chunking/splitter.py): `app/ingestion/chunking/splitter.py`
- [Embedding service](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/services/retrieval/embedding.py): `app/services/retrieval/embedding.py`
- [Vector search](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/services/retrieval/qdrant_service.py): `app/services/retrieval/qdrant_service.py`
- [Semantic reranker](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/services/retrieval/ranking_service.py): `app/services/retrieval/ranking_service.py`

### State and operations

- [Response cache](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/services/cache.py): `app/services/cache.py`
- [LLM gateway client](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/gateway/client.py): `app/gateway/client.py`
- [Conversation checkpoint](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/agents/graph.py): `app/agents/graph.py`
- [Metrics endpoint](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/main.py): `app/main.py`
- [Health checks](https://github.com/ahamed-safnas/agentic-rag/blob/dev/app/health.py): `app/health.py`

### Evaluation

- [Live eval pipeline](https://github.com/ahamed-safnas/agentic-rag/blob/dev/evals/pipeline.py): `evals/pipeline.py`
- [RAG evaluation metrics](https://github.com/ahamed-safnas/agentic-rag/blob/dev/evals/metrics.py): `evals/metrics.py`
- [Guardrails evaluation](https://github.com/ahamed-safnas/agentic-rag/blob/dev/evals/guardrails_eval.py): `evals/guardrails_eval.py`

### Other components

- **User**
- **Qdrant**
- **Jina embeddings API**
- **Jina reranker API**
- **Redis rate limiting**

## Connections

- User → Chat UI: asks question (evidence: `README.md`)
- Chat UI → FastAPI API: submits query (evidence: `README.md`)
- FastAPI API → Guardrails: checks input (evidence: `app/main.py`)
- FastAPI API → Response cache: checks cache (evidence: `app/main.py`)
- FastAPI API → Graph orchestration: runs pipeline (evidence: `app/main.py`)
- Graph orchestration → Query planner: dispatches (evidence: `app/agents/graph.py`)
- Graph orchestration → Document retriever: routes technical (evidence: `app/agents/graph.py`)
- Graph orchestration → Answer responder: routes conversational (evidence: `app/agents/graph.py`)
- Graph orchestration → Agent state: uses state (evidence: `app/agents/graph.py`)
- Query planner → LLM gateway client: requests LLM (evidence: `app/agents/nodes/planner.py`)
- Answer responder → LLM gateway client: requests LLM (evidence: `app/agents/nodes/responder.py`)
- Guardrails → LLM gateway client: requests LLM (evidence: `app/guardrails/rails.py`)
- Document retriever → Vector search: searches (evidence: `app/agents/nodes/retriever.py`)
- Document retriever → Semantic reranker: reranks results (evidence: `app/agents/nodes/retriever.py`)
- Vector search → Embedding service: embeds query (evidence: `app/services/retrieval/qdrant_service.py`)
- Vector search → Qdrant: queries vectors (evidence: `app/services/retrieval/qdrant_service.py`)
- Semantic reranker → Jina reranker API: reranks documents (evidence: `app/services/retrieval/ranking_service.py`)
- Embedding service → Jina embeddings API: embeds texts (evidence: `app/services/retrieval/embedding.py`)
- Ingestion processor → Document loaders: parses files (evidence: `app/ingestion/processor.py`)
- Ingestion processor → Text chunker: chunks text (evidence: `app/ingestion/processor.py`)
- Ingestion processor → Embedding service: embeds chunks (evidence: `app/ingestion/processor.py`)
- Ingestion processor → Qdrant: upserts vectors (evidence: `app/ingestion/processor.py`)
- Graph orchestration → Conversation checkpoint: checkpoints state (evidence: `app/agents/graph.py`)
- FastAPI API → Redis rate limiting: limits requests (evidence: `README.md`)
- FastAPI API → Metrics endpoint: exposes metrics (evidence: `app/main.py`)
- FastAPI API → Health checks: includes health routes (evidence: `app/main.py`)
- Live eval pipeline → FastAPI API: submits live queries (evidence: `evals/pipeline.py`)
- Live eval pipeline → RAG evaluation metrics: evaluates results
- Live eval pipeline → Guardrails evaluation: evaluates safety
