# ldgen404/gpt-researcher architecture

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

- Interactive diagram: https://gitdiagram.com/ldgen404/gpt-researcher
- Repository: https://github.com/ldgen404/gpt-researcher

## Overview

GPT Researcher is a web- and local-document research agent that produces cited reports. Its documented workflow plans research questions, gathers and summarizes sources, then filters and aggregates findings into a report; the repository also exposes this through a web application and supports multi-agent research, MCP data sources, images, and report chat. The graph combines documented capabilities with source-index relationships; unsampled implementation details and links are omitted where evidence is limited.

Main entry points: [`gpt_researcher/agent.py`](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/agent.py) (Research agent), [`multi_agents/agents/orchestrator.py`](https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/orchestrator.py) (Agent orchestration), [`backend/server/app.py`](https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/app.py) (API routes), [`gpt_researcher/actions/query_processing.py`](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/actions/query_processing.py) (Query planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_frontend["Research UI<br/>[page.tsx]"]
  node_api["API routes<br/>[app.py]"]
  node_ws["WebSocket runner"]
end

subgraph group_runtime["Research runtime"]
  node_gpt["Research agent<br/>[agent.py]"]
  node_planning["Query planning"]
  node_config["Research config<br/>[config.py]"]
  node_prompts["Prompt library<br/>[prompts.py]"]
  node_llm_utils["LLM interface<br/>[llm.py]"]
  node_llm_provider["LLM provider<br/>[base.py]"]
  node_types["Research types<br/>[enum.py]"]
  node_context["Context retrieval<br/>[retriever.py]"]
  node_context_manager["Context management<br/>[context_manager.py]"]
  node_report_generation["Report generation"]
end

subgraph group_sources["Research sources"]
  node_retrievers["Search retrievers"]
  node_scraper["Web scraping<br/>[scraper.py]"]
  node_documents["Local documents<br/>[document.py]"]
  node_mcp["MCP retrieval<br/>[retriever.py]"]
end

subgraph group_agents["Multi-agent research"]
  node_multi_runner["Multi-agent dispatch"]
  node_orchestrator["Agent orchestration<br/>[orchestrator.py]"]
  node_researcher_agent["Research agent<br/>[researcher.py]"]
  node_writer_agent["Writer agent<br/>[writer.py]"]
  node_reviewer_agent["Review and revision<br/>[reviewer.py]"]
  node_publisher_agent["Report publisher<br/>[publisher.py]"]
end

subgraph group_platform["Output and services"]
  node_report_store[("Report store<br/>[report_store.py]")]
  node_images["Image generation<br/>[image_generator.py]"]
end

node_user(("Researcher"))
node_external_web(("Web sources"))
node_external_llm(("LLM service"))
node_external_mcp(("MCP servers"))

node_user -->|"submits research"| node_frontend
node_frontend -.->|"calls API"| node_api
node_api -->|"starts research"| node_ws
node_ws -->|"runs agent"| node_gpt
node_gpt -.->|"plans questions"| node_planning
node_planning -->|"builds prompts"| node_prompts
node_planning -->|"generates queries"| node_llm_utils
node_llm_utils -->|"creates provider"| node_llm_provider
node_gpt -.->|"uses settings"| node_config
node_gpt -.->|"gathers sources"| node_retrievers
node_retrievers -.->|"searches web"| node_external_web
node_gpt -.->|"scrapes pages"| node_scraper
node_scraper -.->|"fetches pages"| node_external_web
node_gpt -.->|"reads local files"| node_documents
node_gpt -.->|"uses MCP sources"| node_mcp
node_mcp -.->|"queries tools"| node_external_mcp
node_gpt -.->|"retrieves context"| node_context
node_gpt -.->|"manages context"| node_context_manager
node_gpt -.->|"writes report"| node_report_generation
node_gpt -.->|"requests completions"| node_llm_utils
node_llm_provider -.->|"generates text"| node_external_llm
node_api -->|"dispatches workflow"| node_multi_runner
node_multi_runner -->|"runs agents"| node_orchestrator
node_orchestrator -->|"coordinates research"| node_researcher_agent
node_orchestrator -->|"coordinates writing"| node_writer_agent
node_orchestrator -.->|"routes review"| node_reviewer_agent
node_orchestrator -->|"coordinates publishing"| node_publisher_agent
node_api -->|"reads reports"| node_report_store
node_gpt -.->|"generates illustrations"| node_images

click node_frontend "https://github.com/ldgen404/gpt-researcher/blob/main/frontend/nextjs/app/page.tsx"
click node_api "https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/app.py"
click node_ws "https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/websocket_manager.py"
click node_gpt "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/agent.py"
click node_planning "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/actions/query_processing.py"
click node_config "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/config/config.py"
click node_prompts "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/prompts.py"
click node_llm_utils "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/utils/llm.py"
click node_llm_provider "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/llm_provider/generic/base.py"
click node_types "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/utils/enum.py"
click node_retrievers "https://github.com/ldgen404/gpt-researcher/tree/main/gpt_researcher/retrievers"
click node_scraper "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/scraper/scraper.py"
click node_documents "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/document/document.py"
click node_mcp "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/retrievers/mcp/retriever.py"
click node_context "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/context/retriever.py"
click node_context_manager "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/skills/context_manager.py"
click node_report_generation "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/actions/report_generation.py"
click node_multi_runner "https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/multi_agent_runner.py"
click node_orchestrator "https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/orchestrator.py"
click node_researcher_agent "https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/researcher.py"
click node_writer_agent "https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/writer.py"
click node_reviewer_agent "https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/reviewer.py"
click node_publisher_agent "https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/publisher.py"
click node_report_store "https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/report_store.py"
click node_images "https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/llm_provider/image/image_generator.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_api,node_ws toneBlue
class node_gpt,node_planning,node_config,node_prompts,node_llm_utils,node_llm_provider,node_types,node_context,node_context_manager,node_report_generation toneAmber
class node_retrievers,node_scraper,node_documents,node_mcp,node_external_mcp toneMint
class node_multi_runner,node_orchestrator,node_researcher_agent,node_writer_agent,node_reviewer_agent,node_publisher_agent toneRose
class node_report_store,node_images,node_user,node_external_web,node_external_llm toneIndigo
```

## Components

### User interfaces

- [Research UI](https://github.com/ldgen404/gpt-researcher/blob/main/frontend/nextjs/app/page.tsx): `frontend/nextjs/app/page.tsx`
- [API routes](https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/app.py): `backend/server/app.py`
- [WebSocket runner](https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/websocket_manager.py): `backend/server/websocket_manager.py`

### Research runtime

- [Research agent](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/agent.py): `gpt_researcher/agent.py`
- [Query planning](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/actions/query_processing.py): `gpt_researcher/actions/query_processing.py`
- [Research config](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/config/config.py): `gpt_researcher/config/config.py`
- [Prompt library](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/prompts.py): `gpt_researcher/prompts.py`
- [LLM interface](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/utils/llm.py): `gpt_researcher/utils/llm.py`
- [LLM provider](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/llm_provider/generic/base.py): `gpt_researcher/llm_provider/generic/base.py`
- [Research types](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/utils/enum.py): `gpt_researcher/utils/enum.py`
- [Context retrieval](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/context/retriever.py): `gpt_researcher/context/retriever.py`
- [Context management](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/skills/context_manager.py): `gpt_researcher/skills/context_manager.py`
- [Report generation](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/actions/report_generation.py): `gpt_researcher/actions/report_generation.py`

### Research sources

- [Search retrievers](https://github.com/ldgen404/gpt-researcher/tree/main/gpt_researcher/retrievers): `gpt_researcher/retrievers`
- [Web scraping](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/scraper/scraper.py): `gpt_researcher/scraper/scraper.py`
- [Local documents](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/document/document.py): `gpt_researcher/document/document.py`
- [MCP retrieval](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/retrievers/mcp/retriever.py): `gpt_researcher/retrievers/mcp/retriever.py`

### Multi-agent research

- [Multi-agent dispatch](https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/multi_agent_runner.py): `backend/server/multi_agent_runner.py`
- [Agent orchestration](https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/orchestrator.py): `multi_agents/agents/orchestrator.py`
- [Research agent](https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/researcher.py): `multi_agents/agents/researcher.py`
- [Writer agent](https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/writer.py): `multi_agents/agents/writer.py`
- [Review and revision](https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/reviewer.py): `multi_agents/agents/reviewer.py`
- [Report publisher](https://github.com/ldgen404/gpt-researcher/blob/main/multi_agents/agents/publisher.py): `multi_agents/agents/publisher.py`

### Output and services

- [Report store](https://github.com/ldgen404/gpt-researcher/blob/main/backend/server/report_store.py): `backend/server/report_store.py`
- [Image generation](https://github.com/ldgen404/gpt-researcher/blob/main/gpt_researcher/llm_provider/image/image_generator.py): `gpt_researcher/llm_provider/image/image_generator.py`

### Other components

- **Researcher**
- **Web sources**
- **LLM service**
- **MCP servers**

## Connections

- Researcher → Research UI: submits research (evidence: `README.md`)
- Research UI → API routes: calls API
- API routes → WebSocket runner: starts research (evidence: `backend/server/app.py`)
- WebSocket runner → Research agent: runs agent (evidence: `backend/server/websocket_manager.py`)
- Research agent → Query planning: plans questions
- Query planning → Prompt library: builds prompts (evidence: `gpt_researcher/actions/query_processing.py`)
- Query planning → LLM interface: generates queries (evidence: `gpt_researcher/actions/query_processing.py`)
- LLM interface → LLM provider: creates provider (evidence: `gpt_researcher/utils/llm.py`)
- Research agent → Research config: uses settings
- Research agent → Search retrievers: gathers sources (evidence: `README.md`)
- Search retrievers → Web sources: searches web (evidence: `README.md`)
- Research agent → Web scraping: scrapes pages (evidence: `README.md`)
- Web scraping → Web sources: fetches pages (evidence: `README.md`)
- Research agent → Local documents: reads local files (evidence: `README.md`)
- Research agent → MCP retrieval: uses MCP sources (evidence: `README.md`)
- MCP retrieval → MCP servers: queries tools (evidence: `README.md`)
- Research agent → Context retrieval: retrieves context
- Research agent → Context management: manages context
- Research agent → Report generation: writes report (evidence: `README.md`)
- Research agent → LLM interface: requests completions
- LLM provider → LLM service: generates text
- API routes → Multi-agent dispatch: dispatches workflow (evidence: `backend/server/app.py`)
- Multi-agent dispatch → Agent orchestration: runs agents (evidence: `backend/server/multi_agent_runner.py`)
- Agent orchestration → Research agent: coordinates research (evidence: `multi_agents/agents/orchestrator.py`)
- Agent orchestration → Writer agent: coordinates writing (evidence: `multi_agents/agents/orchestrator.py`)
- Agent orchestration → Review and revision: routes review
- Agent orchestration → Report publisher: coordinates publishing (evidence: `multi_agents/agents/orchestrator.py`)
- API routes → Report store: reads reports (evidence: `backend/server/app.py`)
- Research agent → Image generation: generates illustrations (evidence: `README.md`)
