# mudasserafzal/research-gap-finder architecture

> Architecture diagram of the GitHub repository mudasserafzal/research-gap-finder, 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/mudasserafzal/research-gap-finder
- Repository: https://github.com/mudasserafzal/research-gap-finder

## Overview

Research Gap Finder turns a topic into a literature review and actionable research ideas. Its main workflow expands the query, searches arXiv and Semantic Scholar, traverses citations, deduplicates papers, summarizes them, synthesizes gaps, generates ideas, and formats a report. Users can initiate research through the CLI, API, chat, or MCP tools; the API also supports tenant-scoped asynchronous jobs and follow-up chat. The graph reflects documented capabilities and indexed imports; some detailed route and MCP wiring is not shown in the excerpts.

Main entry points: [`agent/orchestrator.py`](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/orchestrator.py) (Pipeline Orchestrator), [`agent/llm.py`](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/llm.py) (LLM Client), [`agent/state.py`](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/state.py) (Configuration), [`api/routes.py`](https://github.com/mudasserafzal/research-gap-finder/blob/main/api/routes.py) (FastAPI Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Points"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["FastAPI Routes<br/>[routes.py]"]
  node_app["API App<br/>[main.py]"]
  node_mcp["MCP Tools<br/>[mcp_server.py]"]
  node_chat["Chat Handler<br/>[chat_handler.py]"]
end

subgraph group_research["Research Pipeline"]
  node_orchestrator["Pipeline Orchestrator<br/>[orchestrator.py]"]
  node_expander["Query Expansion<br/>[query_expander.py]"]
  node_dedup["Paper Deduplication<br/>[orchestrator.py]"]
end

subgraph group_analysis["LLM Analysis"]
  node_summarizer["Paper Summarizer<br/>[summarizer.py]"]
  node_synthesizer["Gap Synthesizer<br/>[synthesizer.py]"]
  node_ideas["Idea Generator<br/>[idea_generator.py]"]
  node_reporter["Report Formatter<br/>[reporter.py]"]
end

subgraph group_platform["Shared Services"]
  node_models["Research Models<br/>[models.py]"]
  node_state["Configuration<br/>[state.py]"]
  node_llm["LLM Client<br/>[llm.py]"]
end

subgraph group_sources["Literature Sources"]
  node_arxiv["arXiv Fetcher<br/>[arxiv_fetcher.py]"]
  node_semantic["Semantic Scholar Fetcher"]
  node_citations["Citation Traversal"]
end

node_user(("Researcher"))
node_azure{{"Azure OpenAI"}}
node_arxiv_service{{"arXiv API"}}
node_ss_service{{"Semantic Scholar API"}}

node_user -->|"submits query"| node_cli
node_user -->|"starts research"| node_api
node_user -->|"calls tools"| node_mcp
node_app -->|"registers routes"| node_api
node_cli -->|"runs pipeline"| node_orchestrator
node_api -->|"starts job"| node_orchestrator
node_api -->|"handles chat"| node_chat
node_chat -->|"classifies and answers"| node_llm
node_mcp -->|"runs research"| node_orchestrator
node_orchestrator -->|"expands query"| node_expander
node_expander -->|"requests structured output"| node_llm
node_orchestrator -->|"searches papers"| node_arxiv
node_orchestrator -->|"searches papers"| node_semantic
node_orchestrator -->|"traverses citations"| node_citations
node_orchestrator -->|"deduplicates papers"| node_dedup
node_orchestrator -->|"summarizes papers"| node_summarizer
node_summarizer -->|"requests summaries"| node_llm
node_orchestrator -->|"analyzes summaries"| node_synthesizer
node_synthesizer -->|"requests gap analysis"| node_llm
node_orchestrator -->|"generates ideas"| node_ideas
node_ideas -->|"requests ideas"| node_llm
node_orchestrator -->|"formats report"| node_reporter
node_orchestrator -->|"uses typed state"| node_models
node_llm -->|"sends completions"| node_azure
node_arxiv -->|"queries"| node_arxiv_service
node_semantic -->|"queries"| node_ss_service
node_citations -->|"fetches graph"| node_ss_service
node_state -->|"configures access"| node_arxiv
node_state -->|"configures access"| node_semantic
node_state -->|"configures access"| node_citations
node_state -->|"sets model options"| node_llm

click node_cli "https://github.com/mudasserafzal/research-gap-finder/blob/main/cli.py"
click node_api "https://github.com/mudasserafzal/research-gap-finder/blob/main/api/routes.py"
click node_app "https://github.com/mudasserafzal/research-gap-finder/blob/main/main.py"
click node_mcp "https://github.com/mudasserafzal/research-gap-finder/blob/main/mcp_server.py"
click node_chat "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/chat_handler.py"
click node_orchestrator "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/orchestrator.py"
click node_expander "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/query_expander.py"
click node_arxiv "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/fetchers/arxiv_fetcher.py"
click node_semantic "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/fetchers/semantic_fetcher.py"
click node_citations "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/fetchers/citation_fetcher.py"
click node_dedup "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/orchestrator.py"
click node_summarizer "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/summarizer.py"
click node_synthesizer "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/synthesizer.py"
click node_ideas "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/idea_generator.py"
click node_reporter "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/reporter.py"
click node_models "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/models.py"
click node_state "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/state.py"
click node_llm "https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/llm.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_cli,node_api,node_app,node_mcp,node_chat toneBlue
class node_orchestrator,node_expander,node_dedup toneAmber
class node_summarizer,node_synthesizer,node_ideas,node_reporter,node_arxiv_service,node_ss_service toneMint
class node_models,node_state,node_llm toneRose
class node_arxiv,node_semantic,node_citations,node_user,node_azure toneIndigo
```

## Components

### Entry Points

- [CLI](https://github.com/mudasserafzal/research-gap-finder/blob/main/cli.py): `cli.py`
- [FastAPI Routes](https://github.com/mudasserafzal/research-gap-finder/blob/main/api/routes.py): `api/routes.py`
- [API App](https://github.com/mudasserafzal/research-gap-finder/blob/main/main.py): `main.py`
- [MCP Tools](https://github.com/mudasserafzal/research-gap-finder/blob/main/mcp_server.py): `mcp_server.py`
- [Chat Handler](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/chat_handler.py): `agent/chat_handler.py`

### Research Pipeline

- [Pipeline Orchestrator](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/orchestrator.py): `agent/orchestrator.py`
- [Query Expansion](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/query_expander.py): `agent/query_expander.py`
- [Paper Deduplication](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/orchestrator.py): `agent/orchestrator.py`

### LLM Analysis

- [Paper Summarizer](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/summarizer.py): `agent/summarizer.py`
- [Gap Synthesizer](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/synthesizer.py): `agent/synthesizer.py`
- [Idea Generator](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/idea_generator.py): `agent/idea_generator.py`
- [Report Formatter](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/reporter.py): `agent/reporter.py`

### Shared Services

- [Research Models](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/models.py): `agent/models.py`
- [Configuration](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/state.py): `agent/state.py`
- [LLM Client](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/llm.py): `agent/llm.py`

### Literature Sources

- [arXiv Fetcher](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/fetchers/arxiv_fetcher.py): `agent/fetchers/arxiv_fetcher.py`
- [Semantic Scholar Fetcher](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/fetchers/semantic_fetcher.py): `agent/fetchers/semantic_fetcher.py`
- [Citation Traversal](https://github.com/mudasserafzal/research-gap-finder/blob/main/agent/fetchers/citation_fetcher.py): `agent/fetchers/citation_fetcher.py`

### Other components

- **Researcher**
- **Azure OpenAI**
- **arXiv API**
- **Semantic Scholar API**

## Connections

- Researcher → CLI: submits query (evidence: `README.md`)
- Researcher → FastAPI Routes: starts research (evidence: `README.md`)
- Researcher → MCP Tools: calls tools (evidence: `README.md`)
- API App → FastAPI Routes: registers routes (evidence: `main.py`)
- CLI → Pipeline Orchestrator: runs pipeline (evidence: `cli.py`)
- FastAPI Routes → Pipeline Orchestrator: starts job (evidence: `api/routes.py`)
- FastAPI Routes → Chat Handler: handles chat (evidence: `api/routes.py`)
- Chat Handler → LLM Client: classifies and answers (evidence: `agent/chat_handler.py`)
- MCP Tools → Pipeline Orchestrator: runs research (evidence: `mcp_server.py`)
- Pipeline Orchestrator → Query Expansion: expands query (evidence: `agent/orchestrator.py`)
- Query Expansion → LLM Client: requests structured output (evidence: `agent/query_expander.py`)
- Pipeline Orchestrator → arXiv Fetcher: searches papers (evidence: `agent/orchestrator.py`)
- Pipeline Orchestrator → Semantic Scholar Fetcher: searches papers (evidence: `agent/orchestrator.py`)
- Pipeline Orchestrator → Citation Traversal: traverses citations (evidence: `agent/orchestrator.py`)
- Pipeline Orchestrator → Paper Deduplication: deduplicates papers (evidence: `README.md`)
- Pipeline Orchestrator → Paper Summarizer: summarizes papers (evidence: `agent/orchestrator.py`)
- Paper Summarizer → LLM Client: requests summaries (evidence: `agent/summarizer.py`)
- Pipeline Orchestrator → Gap Synthesizer: analyzes summaries (evidence: `agent/orchestrator.py`)
- Gap Synthesizer → LLM Client: requests gap analysis (evidence: `agent/synthesizer.py`)
- Pipeline Orchestrator → Idea Generator: generates ideas (evidence: `agent/orchestrator.py`)
- Idea Generator → LLM Client: requests ideas (evidence: `agent/idea_generator.py`)
- Pipeline Orchestrator → Report Formatter: formats report (evidence: `README.md`)
- Pipeline Orchestrator → Research Models: uses typed state (evidence: `agent/orchestrator.py`)
- LLM Client → Azure OpenAI: sends completions (evidence: `agent/llm.py`)
- arXiv Fetcher → arXiv API: queries (evidence: `agent/fetchers/arxiv_fetcher.py`)
- Semantic Scholar Fetcher → Semantic Scholar API: queries (evidence: `agent/fetchers/semantic_fetcher.py`)
- Citation Traversal → Semantic Scholar API: fetches graph (evidence: `agent/fetchers/citation_fetcher.py`)
- Configuration → arXiv Fetcher: configures access (evidence: `agent/fetchers/arxiv_fetcher.py`)
- Configuration → Semantic Scholar Fetcher: configures access (evidence: `agent/fetchers/semantic_fetcher.py`)
- Configuration → Citation Traversal: configures access (evidence: `agent/fetchers/citation_fetcher.py`)
- Configuration → LLM Client: sets model options (evidence: `agent/llm.py`)