# wahhabriaz/agentic-document-rag architecture

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

- Interactive diagram: https://gitdiagram.com/wahhabriaz/agentic-document-rag
- Repository: https://github.com/wahhabriaz/agentic-document-rag

## Overview

HybridRAG is a PDF assistant: users upload documents, then ask questions answered from both retrieved text and extracted tables. The graph follows the documented upload and Q&A flows through the FastAPI backend, processing/storage stages, and agent system, while retaining the Streamlit client and data-clearing capability. Some source excerpts are partial; uncertain internal dispatch is shown as unverified rather than asserted.

Main entry points: [`src/backend/routes/chat.py`](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/routes/chat.py) (Chat API), [`src/backend/agents/manager_agent.py`](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/manager_agent.py) (Manager Agent), [`src/backend/services/clear_data_service.py`](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/services/clear_data_service.py) (Clear Data Service), [`src/backend/utils/upload_pdf.py`](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/utils/upload_pdf.py) (Upload Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Interface"]
  node_frontend["Streamlit UI<br/>[streamlit_app.py]"]
end

subgraph group_api["API and Services"]
  node_app["FastAPI App<br/>[__init__.py]"]
  node_routes["Chat API<br/>[chat.py]"]
  node_models["API Models<br/>[models.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_orchestrator["Query Orchestrator<br/>[orchestrator.py]"]
  node_clear_service["Clear Data Service"]
  node_clear_script["Clear Data CLI"]
end

subgraph group_ingest["PDF Ingestion"]
  node_upload["Upload Handler<br/>[upload_pdf.py]"]
  node_processor["PDF Processor<br/>[pdf_processor.py]"]
  node_schema["Schema Manager<br/>[schema_manager.py]"]
  node_embedding["Embedding Service"]
end

subgraph group_answer["Answering Agents"]
  node_manager["Manager Agent<br/>[manager_agent.py]"]
  node_rag["RAG Agent<br/>[rag_agent.py]"]
  node_table["Table Agent<br/>[table_agent.py]"]
  node_combiner["Response Combiner<br/>[combiner_agent.py]"]
  node_base["Agent Base<br/>[base.py]"]
end

subgraph group_storage["Data Stores"]
  node_pinecone[("Pinecone Index")]
  node_mysql[("MySQL Tables")]
end

node_user(("User"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_routes
node_app -->|"registers"| node_routes
node_routes -->|"validates"| node_models
node_routes -->|"dispatches upload"| node_upload
node_upload -->|"extracts content"| node_processor
node_upload -->|"stores embeddings"| node_embedding
node_processor -->|"stores tables"| node_mysql
node_embedding -->|"stores vectors"| node_pinecone
node_processor -.->|"manages schemas"| node_schema
node_routes -->|"submits query"| node_orchestrator
node_orchestrator -.->|"dispatches query"| node_manager
node_manager -->|"runs retrieval"| node_rag
node_manager -->|"runs table query"| node_table
node_manager -->|"combines answers"| node_combiner
node_rag -->|"searches vectors"| node_pinecone
node_table -->|"queries tables"| node_mysql
node_rag -->|"extends"| node_base
node_app -->|"initializes"| node_orchestrator
node_routes -->|"clears data"| node_clear_service
node_clear_service -->|"deletes vectors"| node_pinecone
node_clear_service -->|"drops tables"| node_mysql
node_clear_script -->|"clears vectors"| node_pinecone
node_clear_script -->|"clears tables"| node_mysql
node_config -->|"configures"| node_app

click node_frontend "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/frontend/streamlit_app.py"
click node_app "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/__init__.py"
click node_routes "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/routes/chat.py"
click node_models "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/models.py"
click node_config "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/config.py"
click node_orchestrator "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/services/orchestrator.py"
click node_upload "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/utils/upload_pdf.py"
click node_processor "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/utils/pdf_processor.py"
click node_schema "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/utils/schema_manager.py"
click node_embedding "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/services/embedding_service.py"
click node_manager "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/manager_agent.py"
click node_rag "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/rag_agent.py"
click node_table "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/table_agent.py"
click node_combiner "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/combiner_agent.py"
click node_base "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/base.py"
click node_clear_service "https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/services/clear_data_service.py"
click node_clear_script "https://github.com/wahhabriaz/agentic-document-rag/blob/main/clear_data_script.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_frontend,node_user toneBlue
class node_app,node_routes,node_models,node_config,node_orchestrator,node_clear_service,node_clear_script toneAmber
class node_upload,node_processor,node_schema,node_embedding toneMint
class node_manager,node_rag,node_table,node_combiner,node_base toneRose
class node_pinecone,node_mysql toneIndigo
```

## Components

### User Interface

- [Streamlit UI](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/frontend/streamlit_app.py): `src/frontend/streamlit_app.py`

### API and Services

- [FastAPI App](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/__init__.py): `src/backend/__init__.py`
- [Chat API](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/routes/chat.py): `src/backend/routes/chat.py`
- [API Models](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/models.py): `src/backend/models.py`
- [Configuration](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/config.py): `src/backend/config.py`
- [Query Orchestrator](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/services/orchestrator.py): `src/backend/services/orchestrator.py`
- [Clear Data Service](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/services/clear_data_service.py): `src/backend/services/clear_data_service.py`
- [Clear Data CLI](https://github.com/wahhabriaz/agentic-document-rag/blob/main/clear_data_script.py): `clear_data_script.py`

### PDF Ingestion

- [Upload Handler](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/utils/upload_pdf.py): `src/backend/utils/upload_pdf.py`
- [PDF Processor](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/utils/pdf_processor.py): `src/backend/utils/pdf_processor.py`
- [Schema Manager](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/utils/schema_manager.py): `src/backend/utils/schema_manager.py`
- [Embedding Service](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/services/embedding_service.py): `src/backend/services/embedding_service.py`

### Answering Agents

- [Manager Agent](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/manager_agent.py): `src/backend/agents/manager_agent.py`
- [RAG Agent](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/rag_agent.py): `src/backend/agents/rag_agent.py`
- [Table Agent](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/table_agent.py): `src/backend/agents/table_agent.py`
- [Response Combiner](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/combiner_agent.py): `src/backend/agents/combiner_agent.py`
- [Agent Base](https://github.com/wahhabriaz/agentic-document-rag/blob/main/src/backend/agents/base.py): `src/backend/agents/base.py`

### Data Stores

- **Pinecone Index**
- **MySQL Tables**

### Other components

- **User**

## Connections

- User → Streamlit UI: uses (evidence: `README.md`)
- Streamlit UI → Chat API: calls API (evidence: `README.md`)
- FastAPI App → Chat API: registers (evidence: `src/backend/__init__.py`)
- Chat API → API Models: validates (evidence: `src/backend/routes/chat.py`)
- Chat API → Upload Handler: dispatches upload (evidence: `src/backend/routes/chat.py`)
- Upload Handler → PDF Processor: extracts content (evidence: `src/backend/utils/upload_pdf.py`)
- Upload Handler → Embedding Service: stores embeddings (evidence: `src/backend/utils/upload_pdf.py`)
- PDF Processor → MySQL Tables: stores tables (evidence: `README.md`)
- Embedding Service → Pinecone Index: stores vectors (evidence: `src/backend/services/embedding_service.py`)
- PDF Processor → Schema Manager: manages schemas
- Chat API → Query Orchestrator: submits query (evidence: `src/backend/routes/chat.py`)
- Query Orchestrator → Manager Agent: dispatches query
- Manager Agent → RAG Agent: runs retrieval (evidence: `src/backend/agents/manager_agent.py`)
- Manager Agent → Table Agent: runs table query (evidence: `src/backend/agents/manager_agent.py`)
- Manager Agent → Response Combiner: combines answers (evidence: `src/backend/agents/manager_agent.py`)
- RAG Agent → Pinecone Index: searches vectors (evidence: `src/backend/agents/rag_agent.py`)
- Table Agent → MySQL Tables: queries tables (evidence: `README.md`)
- RAG Agent → Agent Base: extends (evidence: `src/backend/agents/rag_agent.py`)
- FastAPI App → Query Orchestrator: initializes (evidence: `src/backend/__init__.py`)
- Chat API → Clear Data Service: clears data (evidence: `src/backend/routes/chat.py`)
- Clear Data Service → Pinecone Index: deletes vectors (evidence: `src/backend/services/clear_data_service.py`)
- Clear Data Service → MySQL Tables: drops tables (evidence: `src/backend/services/clear_data_service.py`)
- Clear Data CLI → Pinecone Index: clears vectors (evidence: `clear_data_script.py`)
- Clear Data CLI → MySQL Tables: clears tables (evidence: `clear_data_script.py`)
- Configuration → FastAPI App: configures (evidence: `src/backend/__init__.py`)