# codinghub27/advanced-deep-research-agent architecture

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

- Interactive diagram: https://gitdiagram.com/codinghub27/advanced-deep-research-agent
- Repository: https://github.com/codinghub27/advanced-deep-research-agent

## Overview

Deep Research Agent is a FastAPI research service: an authenticated user submits a question, the agent researches it across routed sources, synthesizes a cited answer, and can retain the turn in a session. The README describes a phased upgrade workflow rather than product behavior; the architecture here is inferred from the tree and sampled source. The graph and RAG excerpts document their own routing explicitly; unsampled pipeline and endpoint internals limit certainty about some call relationships.

Main entry points: [`research_app/agent/graph.py`](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/graph.py) (Agent graph), [`research_app/main.py`](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/main.py) (FastAPI endpoints), [`research_app/agent/pipeline/rag_nodes.py`](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/rag_nodes.py) (Source RAG nodes), [`research_app/sources/routing/executor.py`](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/routing/executor.py) (Search execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and sessions"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_service["Research service"]
  node_conversation["Conversation context<br/>[context.py]"]
end

subgraph group_agent["Research pipeline"]
  node_graph["Agent graph<br/>[graph.py]"]
  node_state["Query classification<br/>[state.py]"]
  node_planner["Research planning<br/>[nodes.py]"]
  node_taskrouter["Task source routing<br/>[task_router.py]"]
  node_executor["Search execution<br/>[executor.py]"]
  node_evidence["Evidence collection<br/>[evidence.py]"]
  node_gaps["Gap search<br/>[gaps.py]"]
  node_critic["Answer critique<br/>[critic.py]"]
  node_synthesis["Answer synthesis<br/>[synthesis.py]"]
  node_response["Response formatting<br/>[response.py]"]
end

subgraph group_sources["Source discovery"]
  node_official["Official docs source<br/>[adapter.py]"]
  node_web["Web search<br/>[tavily.py]"]
  node_other_sources["Source adapters<br/>[adapters.py]"]
end

subgraph group_rag["Stored-source RAG"]
  node_source_rag["Source RAG nodes<br/>[rag_nodes.py]"]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
  node_indexer["Source indexer<br/>[ingest.py]"]
  node_vector_store[("Chunk store<br/>[store.py]")]
end

subgraph group_persistence["Persistence"]
  node_database[("Application database<br/>[database.py]")]
  node_conversation_repo["Conversation records<br/>[conversations.py]"]
end

node_user(("Research user"))
node_llm{{"Language model"}}

node_user -->|"submits request"| node_api
node_api -->|"checks identity"| node_auth
node_api -->|"prepares research"| node_service
node_api -->|"runs research"| node_graph
node_service -->|"loads and saves turns"| node_conversation_repo
node_service -->|"builds context"| node_conversation
node_conversation_repo -->|"reads and writes"| node_database
node_graph -->|"classifies query"| node_state
node_graph -->|"plans tasks"| node_planner
node_graph -.->|"routes optional RAG"| node_source_rag
node_source_rag -->|"retrieves chunks"| node_retriever
node_retriever -->|"searches chunks"| node_vector_store
node_source_rag -->|"falls back to pipeline"| node_graph
node_graph -->|"routes tasks"| node_taskrouter
node_graph -->|"executes searches"| node_executor
node_executor -->|"dispatches docs search"| node_official
node_executor -->|"dispatches web search"| node_web
node_executor -->|"dispatches source search"| node_other_sources
node_graph -->|"collects evidence"| node_evidence
node_graph -->|"searches evidence gaps"| node_gaps
node_graph -->|"checks answer"| node_critic
node_graph -->|"synthesizes findings"| node_synthesis
node_graph -->|"formats response"| node_response
node_planner -->|"requests planning"| node_llm
node_synthesis -->|"requests synthesis"| node_llm
node_critic -->|"requests critique"| node_llm
node_response -.->|"indexes sources"| node_source_rag
node_source_rag -->|"indexes documents"| node_indexer
node_indexer -->|"writes chunks"| node_vector_store
node_api -->|"returns answer or stream"| node_user

click node_api "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/main.py"
click node_auth "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/auth/auth.py"
click node_service "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/research_service.py"
click node_conversation "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/conversation/context.py"
click node_graph "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/graph.py"
click node_state "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/state.py"
click node_planner "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/nodes.py"
click node_taskrouter "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/routing/task_router.py"
click node_executor "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/routing/executor.py"
click node_evidence "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/evidence.py"
click node_gaps "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/gaps.py"
click node_critic "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/critic.py"
click node_synthesis "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/synthesis.py"
click node_response "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/response.py"
click node_official "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/official_docs/adapter.py"
click node_web "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/tavily.py"
click node_other_sources "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/routing/adapters.py"
click node_source_rag "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/rag_nodes.py"
click node_retriever "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/rag/retriever.py"
click node_indexer "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/rag/ingest.py"
click node_vector_store "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/rag/store.py"
click node_database "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/db/database.py"
click node_conversation_repo "https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/db/conversations.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_api,node_auth,node_service,node_conversation,node_user toneBlue
class node_graph,node_state,node_planner,node_taskrouter,node_executor,node_evidence,node_gaps,node_critic,node_synthesis,node_response toneAmber
class node_official,node_web,node_other_sources toneMint
class node_source_rag,node_retriever,node_indexer,node_vector_store toneRose
class node_database,node_conversation_repo,node_llm toneIndigo
```

## Components

### API and sessions

- [FastAPI endpoints](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/main.py): `research_app/main.py`
- [Authentication](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/auth/auth.py): `research_app/auth/auth.py`
- [Research service](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/research_service.py): `research_app/research_service.py`
- [Conversation context](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/conversation/context.py): `research_app/conversation/context.py`

### Research pipeline

- [Agent graph](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/graph.py): `research_app/agent/graph.py`
- [Query classification](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/state.py): `research_app/agent/state.py`
- [Research planning](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/nodes.py): `research_app/agent/pipeline/nodes.py`
- [Task source routing](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/routing/task_router.py): `research_app/sources/routing/task_router.py`
- [Search execution](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/routing/executor.py): `research_app/sources/routing/executor.py`
- [Evidence collection](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/evidence.py): `research_app/agent/pipeline/evidence.py`
- [Gap search](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/gaps.py): `research_app/agent/pipeline/gaps.py`
- [Answer critique](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/critic.py): `research_app/agent/pipeline/critic.py`
- [Answer synthesis](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/synthesis.py): `research_app/agent/pipeline/synthesis.py`
- [Response formatting](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/response.py): `research_app/agent/pipeline/response.py`

### Source discovery

- [Official docs source](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/official_docs/adapter.py): `research_app/sources/official_docs/adapter.py`
- [Web search](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/tavily.py): `research_app/sources/tavily.py`
- [Source adapters](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/sources/routing/adapters.py): `research_app/sources/routing/adapters.py`

### Stored-source RAG

- [Source RAG nodes](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/agent/pipeline/rag_nodes.py): `research_app/agent/pipeline/rag_nodes.py`
- [Hybrid retriever](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/rag/retriever.py): `research_app/rag/retriever.py`
- [Source indexer](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/rag/ingest.py): `research_app/rag/ingest.py`
- [Chunk store](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/rag/store.py): `research_app/rag/store.py`

### Persistence

- [Application database](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/db/database.py): `research_app/db/database.py`
- [Conversation records](https://github.com/codinghub27/advanced-deep-research-agent/blob/main/research_app/db/conversations.py): `research_app/db/conversations.py`

### Other components

- **Research user**
- **Language model**

## Connections

- Research user → FastAPI endpoints: submits request
- FastAPI endpoints → Authentication: checks identity
- FastAPI endpoints → Research service: prepares research
- FastAPI endpoints → Agent graph: runs research
- Research service → Conversation records: loads and saves turns
- Research service → Conversation context: builds context
- Conversation records → Application database: reads and writes
- Agent graph → Query classification: classifies query
- Agent graph → Research planning: plans tasks
- Agent graph → Source RAG nodes: routes optional RAG
- Source RAG nodes → Hybrid retriever: retrieves chunks
- Hybrid retriever → Chunk store: searches chunks
- Source RAG nodes → Agent graph: falls back to pipeline
- Agent graph → Task source routing: routes tasks
- Agent graph → Search execution: executes searches
- Search execution → Official docs source: dispatches docs search
- Search execution → Web search: dispatches web search
- Search execution → Source adapters: dispatches source search
- Agent graph → Evidence collection: collects evidence
- Agent graph → Gap search: searches evidence gaps
- Agent graph → Answer critique: checks answer
- Agent graph → Answer synthesis: synthesizes findings
- Agent graph → Response formatting: formats response
- Research planning → Language model: requests planning
- Answer synthesis → Language model: requests synthesis
- Answer critique → Language model: requests critique
- Response formatting → Source RAG nodes: indexes sources
- Source RAG nodes → Source indexer: indexes documents
- Source indexer → Chunk store: writes chunks
- FastAPI endpoints → Research user: returns answer or stream