# ishan-debugg/research-agent architecture

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

- Interactive diagram: https://gitdiagram.com/ishan-debugg/research-agent
- Repository: https://github.com/ishan-debugg/research-agent

## Overview

Research Copilot turns a topic query into ranked, structured paper research and an inter-paper knowledge graph. The backend coordinates retrieval, reranking, PDF parsing, extraction, and synthesis; the frontend streams progress and presents results, benchmarks, graph, history, and optional tech-stack matching. README documents the main pipeline and capabilities; sampled source confirms orchestration, SSE consumption, graph synthesis, and caching, but not every service’s internal calls.

Main entry points: [`backend/app/main.py`](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/main.py) (FastAPI orchestrator), [`frontend/context/ResearchContext.js`](https://github.com/ishan-debugg/research-agent/blob/main/frontend/context/ResearchContext.js) (Research state), [`frontend/app/results/page.js`](https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/results/page.js) (Paper results), [`backend/app/services/cache_service.py`](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/cache_service.py) (Cache service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Research interface"]
  node_search["Search input<br/>[page.js]"]
  node_research_context["Research state<br/>[ResearchContext.js]"]
  node_processing["Live progress<br/>[page.js]"]
  node_results["Paper results<br/>[page.js]"]
  node_benchmarks["Benchmark table"]
  node_graph_view["Knowledge graph view<br/>[GraphView.js]"]
  node_paper_panel["Paper summary panel<br/>[PaperPanel.js]"]
  node_history_page["Search history<br/>[page.js]"]
  node_profile["Profile and theme"]
end

subgraph group_pipeline["Research pipeline"]
  node_api["FastAPI orchestrator<br/>[main.py]"]
  node_schemas["Pipeline schemas<br/>[schemas.py]"]
  node_arxiv["Paper retrieval<br/>[arxiv_service.py]"]
  node_rerank["Semantic reranking<br/>[rerank_service.py]"]
  node_pdf["PDF text extraction<br/>[pdf_service.py]"]
  node_extract["Structured extraction"]
  node_graph["Graph synthesis<br/>[graph_service.py]"]
  node_techmatch["Tech-stack matching"]
end

subgraph group_ai["Model integrations"]
  node_groq_client["Groq client<br/>[groq_client.py]"]
  node_gemini_client["Gemini client<br/>[gemini_client.py]"]
end

subgraph group_state["Persistence"]
  node_history_store["History storage<br/>[historyStore.js]"]
  node_cache_service["Cache service<br/>[cache_service.py]"]
  node_sqlite[("SQLite cache")]
end

node_researcher(("Researcher"))
node_arxiv_service["arXiv"]
node_groq["Groq API"]
node_gemini["Gemini API"]

node_researcher -->|"enters query"| node_search
node_search -->|"starts search"| node_research_context
node_research_context -->|"streams request"| node_api
node_api -->|"retrieves candidates"| node_arxiv
node_arxiv -->|"queries"| node_arxiv_service
node_api -->|"reranks candidates"| node_rerank
node_api -->|"extracts paper text"| node_pdf
node_api -->|"extracts structure"| node_extract
node_api -->|"synthesizes graph"| node_graph
node_api -->|"streams progress and results"| node_research_context
node_research_context -->|"provides live state"| node_processing
node_processing -->|"navigates on completion"| node_results
node_results -->|"reads results"| node_research_context
node_results -->|"renders metrics"| node_benchmarks
node_results -->|"reads tech stack"| node_profile
node_results -.->|"requests tech match"| node_api
node_api -.->|"matches papers"| node_techmatch
node_graph_view -->|"reads graph data"| node_research_context
node_paper_panel -->|"shows selected paper"| node_graph_view
node_history_page -->|"reads entries"| node_history_store
node_research_context -->|"saves completed search"| node_history_store
node_api -->|"validates pipeline data"| node_schemas
node_extract -->|"requests extraction"| node_groq_client
node_extract -.->|"uses fallback"| node_gemini_client
node_graph -->|"requests synthesis"| node_groq_client
node_graph -.->|"uses fallback"| node_gemini_client
node_groq_client -->|"sends model request"| node_groq
node_gemini_client -->|"sends model request"| node_gemini
node_extract -->|"reads and writes extraction cache"| node_cache_service
node_graph -->|"reads and writes graph cache"| node_cache_service
node_pdf -->|"caches paper text"| node_cache_service
node_api -->|"reads and writes query results"| node_cache_service
node_cache_service -->|"persists cache data"| node_sqlite

click node_search "https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/search/page.js"
click node_research_context "https://github.com/ishan-debugg/research-agent/blob/main/frontend/context/ResearchContext.js"
click node_processing "https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/processing/page.js"
click node_results "https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/results/page.js"
click node_benchmarks "https://github.com/ishan-debugg/research-agent/blob/main/frontend/components/BenchmarkExtracted.js"
click node_graph_view "https://github.com/ishan-debugg/research-agent/blob/main/frontend/components/GraphView.js"
click node_paper_panel "https://github.com/ishan-debugg/research-agent/blob/main/frontend/components/PaperPanel.js"
click node_history_page "https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/history/page.js"
click node_history_store "https://github.com/ishan-debugg/research-agent/blob/main/frontend/lib/historyStore.js"
click node_profile "https://github.com/ishan-debugg/research-agent/blob/main/frontend/context/UserProfileContext.js"
click node_api "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/main.py"
click node_schemas "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/models/schemas.py"
click node_arxiv "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/arxiv_service.py"
click node_rerank "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/rerank_service.py"
click node_pdf "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/pdf_service.py"
click node_extract "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/extraction_service.py"
click node_graph "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/graph_service.py"
click node_techmatch "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/techmatch_service.py"
click node_groq_client "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/groq_client.py"
click node_gemini_client "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/gemini_client.py"
click node_cache_service "https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/cache_service.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_search,node_research_context,node_processing,node_results,node_benchmarks,node_graph_view,node_paper_panel,node_history_page,node_profile toneBlue
class node_api,node_schemas,node_arxiv,node_rerank,node_pdf,node_extract,node_graph,node_techmatch toneAmber
class node_groq_client,node_gemini_client,node_groq,node_gemini toneMint
class node_history_store,node_cache_service,node_sqlite toneRose
class node_researcher,node_arxiv_service toneIndigo
```

## Components

### Research interface

- [Search input](https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/search/page.js): `frontend/app/search/page.js`
- [Research state](https://github.com/ishan-debugg/research-agent/blob/main/frontend/context/ResearchContext.js): `frontend/context/ResearchContext.js`
- [Live progress](https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/processing/page.js): `frontend/app/processing/page.js`
- [Paper results](https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/results/page.js): `frontend/app/results/page.js`
- [Benchmark table](https://github.com/ishan-debugg/research-agent/blob/main/frontend/components/BenchmarkExtracted.js): `frontend/components/BenchmarkExtracted.js`
- [Knowledge graph view](https://github.com/ishan-debugg/research-agent/blob/main/frontend/components/GraphView.js): `frontend/components/GraphView.js`
- [Paper summary panel](https://github.com/ishan-debugg/research-agent/blob/main/frontend/components/PaperPanel.js): `frontend/components/PaperPanel.js`
- [Search history](https://github.com/ishan-debugg/research-agent/blob/main/frontend/app/history/page.js): `frontend/app/history/page.js`
- [Profile and theme](https://github.com/ishan-debugg/research-agent/blob/main/frontend/context/UserProfileContext.js): `frontend/context/UserProfileContext.js`

### Research pipeline

- [FastAPI orchestrator](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Pipeline schemas](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`
- [Paper retrieval](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/arxiv_service.py): `backend/app/services/arxiv_service.py`
- [Semantic reranking](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/rerank_service.py): `backend/app/services/rerank_service.py`
- [PDF text extraction](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`
- [Structured extraction](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/extraction_service.py): `backend/app/services/extraction_service.py`
- [Graph synthesis](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/graph_service.py): `backend/app/services/graph_service.py`
- [Tech-stack matching](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/techmatch_service.py): `backend/app/services/techmatch_service.py`

### Model integrations

- [Groq client](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/groq_client.py): `backend/app/services/groq_client.py`
- [Gemini client](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/gemini_client.py): `backend/app/services/gemini_client.py`

### Persistence

- [History storage](https://github.com/ishan-debugg/research-agent/blob/main/frontend/lib/historyStore.js): `frontend/lib/historyStore.js`
- [Cache service](https://github.com/ishan-debugg/research-agent/blob/main/backend/app/services/cache_service.py): `backend/app/services/cache_service.py`
- **SQLite cache**

### Other components

- **Researcher**
- **arXiv**
- **Groq API**
- **Gemini API**

## Connections

- Researcher → Search input: enters query
- Search input → Research state: starts search
- Research state → FastAPI orchestrator: streams request
- FastAPI orchestrator → Paper retrieval: retrieves candidates
- Paper retrieval → arXiv: queries
- FastAPI orchestrator → Semantic reranking: reranks candidates
- FastAPI orchestrator → PDF text extraction: extracts paper text
- FastAPI orchestrator → Structured extraction: extracts structure
- FastAPI orchestrator → Graph synthesis: synthesizes graph
- FastAPI orchestrator → Research state: streams progress and results
- Research state → Live progress: provides live state
- Live progress → Paper results: navigates on completion
- Paper results → Research state: reads results
- Paper results → Benchmark table: renders metrics
- Paper results → Profile and theme: reads tech stack
- Paper results → FastAPI orchestrator: requests tech match
- FastAPI orchestrator → Tech-stack matching: matches papers
- Knowledge graph view → Research state: reads graph data
- Paper summary panel → Knowledge graph view: shows selected paper
- Search history → History storage: reads entries
- Research state → History storage: saves completed search
- FastAPI orchestrator → Pipeline schemas: validates pipeline data
- Structured extraction → Groq client: requests extraction
- Structured extraction → Gemini client: uses fallback
- Graph synthesis → Groq client: requests synthesis
- Graph synthesis → Gemini client: uses fallback
- Groq client → Groq API: sends model request
- Gemini client → Gemini API: sends model request
- Structured extraction → Cache service: reads and writes extraction cache
- Graph synthesis → Cache service: reads and writes graph cache
- PDF text extraction → Cache service: caches paper text
- FastAPI orchestrator → Cache service: reads and writes query results
- Cache service → SQLite cache: persists cache data