# roly-luna/deep-research-agentic-rag architecture

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

- Interactive diagram: https://gitdiagram.com/roly-luna/deep-research-agentic-rag
- Repository: https://github.com/roly-luna/deep-research-agentic-rag

## Overview

Deep Research Agentic RAG is a FastAPI research assistant: users authenticate, submit conversation messages, and receive agent-generated answers grounded in PDF retrieval and external research tools. A separate document workflow uploads and indexes PDFs or searches the knowledge base directly. PostgreSQL supports both vector storage and persistent conversation checkpoints. The main app wires routes and runtime services; route and tool internals were not all excerpted, so some documented capabilities are shown without detailed call paths.

Main entry points: [`app/agent/core.py`](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/agent/core.py) (Deep research agent), [`app/main.py`](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/main.py) (FastAPI app), [`app/api/routes/documents.py`](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/documents.py) (Document endpoints), [`app/vectorstore/pgvector.py`](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/vectorstore/pgvector.py) (PGVector store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth_route["Token endpoint<br/>[auth.py]"]
  node_jwt["JWT security<br/>[security.py]"]
  node_authn["Request authentication<br/>[dependencies.py]"]
  node_conversation_api["Conversation endpoints<br/>[conversations.py]"]
  node_document_api["Document endpoints<br/>[documents.py]"]
  node_health_api["Health endpoints<br/>[health.py]"]
end

subgraph group_research["Research agent"]
  node_agent["Deep research agent<br/>[core.py]"]
  node_prompts["Prompt templates"]
  node_arxiv["arXiv search<br/>[arxiv_search.py]"]
  node_wikipedia["Wikipedia search"]
  node_web["Web search<br/>[web_search.py]"]
  node_research_agent_sub["Research analyst sub-agent"]
end

subgraph group_knowledge["Knowledge base"]
  node_ingestion["PDF ingestion<br/>[pipeline.py]"]
  node_embedding["Gemini embeddings<br/>[gemini.py]"]
  node_vector[("PGVector store<br/>[pgvector.py]")]
  node_retriever["Semantic retrieval<br/>[retriever.py]"]
  node_kb_tool["Knowledge-base tool<br/>[knowledge_base.py]"]
end

subgraph group_runtime["Runtime services"]
  node_postgres[("PostgreSQL<br/>[postgres.py]")]
  node_settings["Application settings<br/>[settings.py]"]
  node_tavily["Tavily search service"]
  node_arxiv_service["arXiv service"]
  node_wikipedia_service["Wikipedia service"]
  node_gemini["Gemini model"]
end

node_user(("API user"))

node_user -->|"calls API"| node_app
node_app -->|"registers routes"| node_auth_route
node_app -->|"registers routes"| node_conversation_api
node_app -->|"registers routes"| node_document_api
node_app -->|"registers routes"| node_health_api
node_auth_route -->|"issues token"| node_jwt
node_conversation_api -->|"requires authentication"| node_authn
node_document_api -->|"requires authentication"| node_authn
node_conversation_api -->|"runs conversation"| node_agent
node_document_api -->|"ingests uploads"| node_ingestion
node_document_api -->|"searches knowledge base"| node_retriever
node_app -->|"creates agent"| node_agent
node_app -->|"opens pool"| node_postgres
node_app -->|"initializes store"| node_vector
node_agent -->|"renders prompt"| node_prompts
node_agent -->|"registers tools"| node_arxiv
node_agent -->|"registers tools"| node_wikipedia
node_agent -->|"registers tools"| node_web
node_agent -->|"registers tools"| node_kb_tool
node_agent -.->|"may delegate"| node_research_agent_sub
node_agent -->|"persists checkpoints"| node_postgres
node_ingestion -->|"stores chunks"| node_vector
node_vector -->|"embeds documents"| node_embedding
node_retriever -->|"searches vectors"| node_vector
node_kb_tool -->|"retrieves passages"| node_retriever
node_arxiv -->|"searches papers"| node_arxiv_service
node_wikipedia -->|"searches articles"| node_wikipedia_service
node_web -->|"searches web"| node_tavily
node_agent -->|"generates answers"| node_gemini
node_app -->|"loads configuration"| node_settings

click node_app "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/main.py"
click node_auth_route "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/auth.py"
click node_jwt "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/auth/security.py"
click node_authn "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/auth/dependencies.py"
click node_conversation_api "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/conversations.py"
click node_document_api "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/documents.py"
click node_health_api "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/health.py"
click node_agent "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/agent/core.py"
click node_prompts "https://github.com/roly-luna/deep-research-agentic-rag/tree/main/app/prompts"
click node_arxiv "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/tools/arxiv_search.py"
click node_wikipedia "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/tools/wikipedia_search.py"
click node_web "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/tools/web_search.py"
click node_research_agent_sub "https://github.com/roly-luna/deep-research-agentic-rag/tree/main/app/tools"
click node_ingestion "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/ingestion/pipeline.py"
click node_embedding "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/embeddings/gemini.py"
click node_vector "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/vectorstore/pgvector.py"
click node_retriever "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/rag/retriever.py"
click node_kb_tool "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/tools/knowledge_base.py"
click node_postgres "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/db/postgres.py"
click node_settings "https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/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_app,node_auth_route,node_jwt,node_authn,node_conversation_api,node_document_api,node_health_api,node_user toneBlue
class node_agent,node_prompts,node_arxiv,node_wikipedia,node_web,node_research_agent_sub toneAmber
class node_ingestion,node_embedding,node_vector,node_retriever,node_kb_tool toneMint
class node_postgres,node_settings,node_tavily,node_arxiv_service,node_wikipedia_service,node_gemini toneRose
```

## Components

### API and access

- [FastAPI app](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/main.py): `app/main.py`
- [Token endpoint](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/auth.py): `app/api/routes/auth.py`
- [JWT security](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/auth/security.py): `app/api/auth/security.py`
- [Request authentication](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/auth/dependencies.py): `app/api/auth/dependencies.py`
- [Conversation endpoints](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/conversations.py): `app/api/routes/conversations.py`
- [Document endpoints](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/documents.py): `app/api/routes/documents.py`
- [Health endpoints](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/api/routes/health.py): `app/api/routes/health.py`

### Research agent

- [Deep research agent](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/agent/core.py): `app/agent/core.py`
- [Prompt templates](https://github.com/roly-luna/deep-research-agentic-rag/tree/main/app/prompts): `app/prompts`
- [arXiv search](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/tools/arxiv_search.py): `app/tools/arxiv_search.py`
- [Wikipedia search](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/tools/wikipedia_search.py): `app/tools/wikipedia_search.py`
- [Web search](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/tools/web_search.py): `app/tools/web_search.py`
- [Research analyst sub-agent](https://github.com/roly-luna/deep-research-agentic-rag/tree/main/app/tools): `app/tools`

### Knowledge base

- [PDF ingestion](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/ingestion/pipeline.py): `app/ingestion/pipeline.py`
- [Gemini embeddings](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/embeddings/gemini.py): `app/embeddings/gemini.py`
- [PGVector store](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/vectorstore/pgvector.py): `app/vectorstore/pgvector.py`
- [Semantic retrieval](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/rag/retriever.py): `app/rag/retriever.py`
- [Knowledge-base tool](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/tools/knowledge_base.py): `app/tools/knowledge_base.py`

### Runtime services

- [PostgreSQL](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/db/postgres.py): `app/db/postgres.py`
- [Application settings](https://github.com/roly-luna/deep-research-agentic-rag/blob/main/app/config/settings.py): `app/config/settings.py`
- **Tavily search service**
- **arXiv service**
- **Wikipedia service**
- **Gemini model**

### Other components

- **API user**

## Connections

- API user → FastAPI app: calls API
- FastAPI app → Token endpoint: registers routes (evidence: `app/main.py`)
- FastAPI app → Conversation endpoints: registers routes (evidence: `app/main.py`)
- FastAPI app → Document endpoints: registers routes (evidence: `app/main.py`)
- FastAPI app → Health endpoints: registers routes (evidence: `app/main.py`)
- Token endpoint → JWT security: issues token (evidence: `app/api/routes/auth.py`)
- Conversation endpoints → Request authentication: requires authentication (evidence: `app/api/routes/conversations.py`)
- Document endpoints → Request authentication: requires authentication (evidence: `app/api/routes/documents.py`)
- Conversation endpoints → Deep research agent: runs conversation (evidence: `app/api/routes/conversations.py`)
- Document endpoints → PDF ingestion: ingests uploads (evidence: `app/api/routes/documents.py`)
- Document endpoints → Semantic retrieval: searches knowledge base (evidence: `app/api/routes/documents.py`)
- FastAPI app → Deep research agent: creates agent (evidence: `app/main.py`)
- FastAPI app → PostgreSQL: opens pool (evidence: `app/main.py`)
- FastAPI app → PGVector store: initializes store (evidence: `app/main.py`)
- Deep research agent → Prompt templates: renders prompt (evidence: `app/agent/core.py`)
- Deep research agent → arXiv search: registers tools (evidence: `app/agent/core.py`)
- Deep research agent → Wikipedia search: registers tools (evidence: `app/agent/core.py`)
- Deep research agent → Web search: registers tools (evidence: `app/agent/core.py`)
- Deep research agent → Knowledge-base tool: registers tools (evidence: `app/agent/core.py`)
- Deep research agent → Research analyst sub-agent: may delegate (evidence: `app/agent/core.py`)
- Deep research agent → PostgreSQL: persists checkpoints
- PDF ingestion → PGVector store: stores chunks (evidence: `app/ingestion/pipeline.py`)
- PGVector store → Gemini embeddings: embeds documents (evidence: `app/vectorstore/pgvector.py`)
- Semantic retrieval → PGVector store: searches vectors (evidence: `app/rag/retriever.py`)
- Knowledge-base tool → Semantic retrieval: retrieves passages (evidence: `app/tools/knowledge_base.py`)
- arXiv search → arXiv service: searches papers
- Wikipedia search → Wikipedia service: searches articles
- Web search → Tavily search service: searches web (evidence: `app/tools/web_search.py`)
- Deep research agent → Gemini model: generates answers
- FastAPI app → Application settings: loads configuration (evidence: `app/main.py`)
