# mohamedtarekmostafa/hybrid-rag-agent architecture

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

- Interactive diagram: https://gitdiagram.com/mohamedtarekmostafa/hybrid-rag-agent
- Repository: https://github.com/mohamedtarekmostafa/hybrid-rag-agent

## Overview

This is an agentic PDF-and-web question-answering application. A user submits a question in Streamlit; the UI sends it to a FastAPI endpoint, which invokes a LangGraph workflow. The router selects PDF retrieval, web search, or direct generation, and the generator returns an answer for the UI. The README also describes conversational memory and persistent checkpoints; the sampled code uses an in-memory checkpointer and a fixed thread ID in the backend. The graph follows explicit calls and documented routing; unsampled behavior is not inferred.

Main entry points: [`nodes.py`](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py) (Query Router), [`main.py`](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/main.py) (Ask API), [`agent.py`](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/agent.py) (Graph Workflow), [`app.py`](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/app.py) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_streamlit["Chat UI<br/>[app.py]"]
  node_api["Ask API<br/>[main.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_graph["Graph Workflow<br/>[agent.py]"]
  node_router["Query Router<br/>[nodes.py]"]
  node_pdf_retrieve["PDF Retrieval<br/>[nodes.py]"]
  node_web_search["Web Search<br/>[nodes.py]"]
  node_generator["Answer Generator<br/>[nodes.py]"]
end

subgraph group_knowledge["Knowledge Sources"]
  node_pdf_index[("PDF Vector Index<br/>[tools.py]")]
  node_tavily["Tavily Search"]
end

subgraph group_models["Models and Memory"]
  node_llm["Groq LLM"]
  node_checkpoint[("Conversation Checkpoint<br/>[agent.py]")]
end

node_user(("User"))

node_user -->|"asks"| node_streamlit
node_streamlit -->|"posts question"| node_api
node_api -->|"invokes"| node_graph
node_api -->|"builds retriever"| node_pdf_index
node_graph -->|"routes with"| node_router
node_router -->|"selects PDF"| node_pdf_retrieve
node_router -->|"selects web"| node_web_search
node_router -->|"selects direct"| node_generator
node_pdf_retrieve -->|"queries"| node_pdf_index
node_web_search -->|"searches"| node_tavily
node_pdf_retrieve -->|"passes context"| node_generator
node_web_search -->|"passes results"| node_generator
node_generator -->|"generates with"| node_llm
node_router -->|"classifies with"| node_llm
node_graph -->|"configures"| node_checkpoint
node_api -->|"returns answer"| node_streamlit

click node_streamlit "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/app.py"
click node_api "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/main.py"
click node_graph "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/agent.py"
click node_router "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py"
click node_pdf_retrieve "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py"
click node_web_search "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py"
click node_generator "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py"
click node_pdf_index "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/tools.py"
click node_checkpoint "https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/agent.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,node_api,node_user toneBlue
class node_graph,node_router,node_pdf_retrieve,node_web_search,node_generator toneAmber
class node_pdf_index,node_tavily toneMint
class node_llm,node_checkpoint toneRose
```

## Components

### User Interface

- [Chat UI](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/app.py): `app.py`
- [Ask API](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/main.py): `main.py`

### Agent Runtime

- [Graph Workflow](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/agent.py): `agent.py`
- [Query Router](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py): `nodes.py`
- [PDF Retrieval](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py): `nodes.py`
- [Web Search](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py): `nodes.py`
- [Answer Generator](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/nodes.py): `nodes.py`

### Knowledge Sources

- [PDF Vector Index](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/tools.py): `tools.py`
- **Tavily Search**

### Models and Memory

- **Groq LLM**
- [Conversation Checkpoint](https://github.com/mohamedtarekmostafa/hybrid-rag-agent/blob/main/agent.py): `agent.py`

### Other components

- **User**

## Connections

- User → Chat UI: asks (evidence: `app.py`)
- Chat UI → Ask API: posts question (evidence: `app.py`)
- Ask API → Graph Workflow: invokes (evidence: `main.py`)
- Ask API → PDF Vector Index: builds retriever (evidence: `main.py`)
- Graph Workflow → Query Router: routes with (evidence: `agent.py`)
- Query Router → PDF Retrieval: selects PDF (evidence: `agent.py`)
- Query Router → Web Search: selects web (evidence: `agent.py`)
- Query Router → Answer Generator: selects direct (evidence: `agent.py`)
- PDF Retrieval → PDF Vector Index: queries (evidence: `nodes.py`)
- Web Search → Tavily Search: searches (evidence: `nodes.py`)
- PDF Retrieval → Answer Generator: passes context (evidence: `agent.py`)
- Web Search → Answer Generator: passes results (evidence: `agent.py`)
- Answer Generator → Groq LLM: generates with (evidence: `nodes.py`)
- Query Router → Groq LLM: classifies with (evidence: `nodes.py`)
- Graph Workflow → Conversation Checkpoint: configures (evidence: `agent.py`)
- Ask API → Chat UI: returns answer (evidence: `main.py`)