# snehilsaxena29/scholar-agent architecture

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

- Interactive diagram: https://gitdiagram.com/snehilsaxena29/scholar-agent
- Repository: https://github.com/snehilsaxena29/scholar-agent

## Overview

Scholar-Agent is a web application for producing literature reviews grounded in retrieved academic papers. A user submits a question; the backend finds papers, extracts and indexes passages, critiques and drafts a review, then verifies it and links sentences to evidence. The frontend streams agent progress, displays the report and sources, and optionally saves runs for signed-in users. The README documents the agent workflow and alternate vector stores; unsampled implementation details are represented only where the source index or documentation supports them.

Main entry points: [`backend2/app/graph/build.py`](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/build.py) (Research graph), [`frontend2/src/pages/Research.jsx`](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/pages/Research.jsx) (Research form), [`backend2/app/graph/nodes/librarian.py`](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/librarian.py) (Librarian), [`backend2/app/main.py`](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/main.py) (FastAPI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Research interface"]
  node_research_page["Research form<br/>[Research.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_trace["Agent trace<br/>[AgentTrace.jsx]"]
  node_report["Report display<br/>[ReportView.jsx]"]
  node_annotations["Report annotations"]
  node_evidence_view["Evidence view<br/>[EvidenceView.jsx]"]
  node_export["Report export<br/>[ExportBar.jsx]"]
  node_auth["Auth context<br/>[AuthContext.jsx]"]
  node_history_page["Research history<br/>[History.jsx]"]
end

subgraph group_api["API and persistence"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_graph["Research graph<br/>[build.py]"]
  node_session_store[("Session database<br/>[models.py]")]
end

subgraph group_retrieval["Paper retrieval"]
  node_paper_search["Paper search<br/>[fetch.py]"]
  node_pdf_parse["PDF parsing<br/>[parse.py]"]
  node_chunking["Text chunking<br/>[chunk.py]"]
  node_embeddings["Embeddings<br/>[embed.py]"]
  node_vector_store[("Vector retrieval<br/>[vectorstore.py]")]
end

subgraph group_agents["Review agents"]
  node_librarian["Librarian<br/>[librarian.py]"]
  node_skeptic["Skeptic<br/>[skeptic.py]"]
  node_synthesizer["Synthesizer<br/>[synthesizer.py]"]
  node_supervisor["Supervisor<br/>[supervisor.py]"]
  node_state["Research state<br/>[state.py]"]
  node_llm_factory["LLM provider client<br/>[llm.py]"]
end

subgraph group_quality["Evidence and evaluation"]
  node_evidence_node["Evidence linking<br/>[evidence.py]"]
  node_evidence_match["Evidence matching<br/>[evidence.py]"]
  node_evaluation["Run evaluation<br/>[metrics.py]"]
end

node_researcher(("Researcher"))
node_supabase_auth["Supabase auth"]
node_academic_sources["Academic paper services"]
node_groq["Groq"]

node_researcher -->|"submits question"| node_research_page
node_research_page -->|"starts stream"| node_api_client
node_api_client -.->|"requests research"| node_api
node_api -->|"runs graph"| node_graph
node_api -->|"streams updates"| node_graph
node_graph -->|"dispatches"| node_librarian
node_graph -->|"dispatches"| node_skeptic
node_graph -->|"dispatches"| node_synthesizer
node_graph -->|"dispatches"| node_supervisor
node_graph -->|"dispatches"| node_evidence_node
node_librarian -->|"fetches papers"| node_paper_search
node_paper_search -.->|"searches"| node_academic_sources
node_librarian -->|"parses papers"| node_pdf_parse
node_librarian -->|"chunks text"| node_chunking
node_librarian -->|"indexes and searches"| node_vector_store
node_vector_store -->|"uses vectors"| node_embeddings
node_librarian -->|"updates retrieval state"| node_state
node_skeptic -->|"gets model"| node_llm_factory
node_synthesizer -->|"gets model"| node_llm_factory
node_supervisor -->|"gets model"| node_llm_factory
node_llm_factory -.->|"invokes model"| node_groq
node_graph -->|"passes state"| node_state
node_supervisor -->|"retries draft"| node_synthesizer
node_evidence_node -->|"matches passages"| node_evidence_match
node_api -->|"scores run"| node_evaluation
node_evaluation -->|"judges with model"| node_llm_factory
node_evaluation -->|"compares vectors"| node_embeddings
node_api -->|"reads and saves history"| node_session_store
node_research_page -->|"renders progress"| node_trace
node_research_page -->|"renders result"| node_report
node_report -->|"renders draft"| node_annotations
node_report -->|"renders evidence"| node_evidence_view
node_research_page -->|"offers export"| node_export
node_auth -->|"gets auth session"| node_supabase_auth
node_history_page -->|"reads session"| node_auth
node_history_page -->|"loads history"| node_api_client
node_research_page -->|"saves signed-in run"| node_api_client

click node_research_page "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/pages/Research.jsx"
click node_api_client "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/lib/api.js"
click node_trace "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/AgentTrace.jsx"
click node_report "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/ReportView.jsx"
click node_annotations "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/AnnotatedReport.jsx"
click node_evidence_view "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/EvidenceView.jsx"
click node_export "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/ExportBar.jsx"
click node_auth "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/lib/AuthContext.jsx"
click node_history_page "https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/pages/History.jsx"
click node_api "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/main.py"
click node_graph "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/build.py"
click node_session_store "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/db/models.py"
click node_librarian "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/librarian.py"
click node_skeptic "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/skeptic.py"
click node_synthesizer "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/synthesizer.py"
click node_supervisor "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/supervisor.py"
click node_state "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/state.py"
click node_paper_search "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/fetch.py"
click node_pdf_parse "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/parse.py"
click node_chunking "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/chunk.py"
click node_embeddings "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/embed.py"
click node_vector_store "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/vectorstore.py"
click node_llm_factory "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/llm.py"
click node_evidence_node "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/evidence.py"
click node_evidence_match "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/eval/evidence.py"
click node_evaluation "https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/eval/metrics.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_research_page,node_api_client,node_trace,node_report,node_annotations,node_evidence_view,node_export,node_auth,node_history_page toneBlue
class node_api,node_graph,node_session_store toneAmber
class node_paper_search,node_pdf_parse,node_chunking,node_embeddings,node_vector_store toneMint
class node_librarian,node_skeptic,node_synthesizer,node_supervisor,node_state,node_llm_factory toneRose
class node_evidence_node,node_evidence_match,node_evaluation,node_researcher,node_supabase_auth,node_academic_sources,node_groq toneIndigo
```

## Components

### Research interface

- [Research form](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/pages/Research.jsx): `frontend2/src/pages/Research.jsx`
- [API client](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/lib/api.js): `frontend2/src/lib/api.js`
- [Agent trace](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/AgentTrace.jsx): `frontend2/src/components/AgentTrace.jsx`
- [Report display](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/ReportView.jsx): `frontend2/src/components/ReportView.jsx`
- [Report annotations](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/AnnotatedReport.jsx): `frontend2/src/components/AnnotatedReport.jsx`
- [Evidence view](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/EvidenceView.jsx): `frontend2/src/components/EvidenceView.jsx`
- [Report export](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/components/ExportBar.jsx): `frontend2/src/components/ExportBar.jsx`
- [Auth context](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/lib/AuthContext.jsx): `frontend2/src/lib/AuthContext.jsx`
- [Research history](https://github.com/snehilsaxena29/scholar-agent/blob/main/frontend2/src/pages/History.jsx): `frontend2/src/pages/History.jsx`

### API and persistence

- [FastAPI routes](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/main.py): `backend2/app/main.py`
- [Research graph](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/build.py): `backend2/app/graph/build.py`
- [Session database](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/db/models.py): `backend2/app/db/models.py`

### Paper retrieval

- [Paper search](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/fetch.py): `backend2/app/ingestion/fetch.py`
- [PDF parsing](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/parse.py): `backend2/app/ingestion/parse.py`
- [Text chunking](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/chunk.py): `backend2/app/ingestion/chunk.py`
- [Embeddings](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/embed.py): `backend2/app/ingestion/embed.py`
- [Vector retrieval](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/ingestion/vectorstore.py): `backend2/app/ingestion/vectorstore.py`

### Review agents

- [Librarian](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/librarian.py): `backend2/app/graph/nodes/librarian.py`
- [Skeptic](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/skeptic.py): `backend2/app/graph/nodes/skeptic.py`
- [Synthesizer](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/synthesizer.py): `backend2/app/graph/nodes/synthesizer.py`
- [Supervisor](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/supervisor.py): `backend2/app/graph/nodes/supervisor.py`
- [Research state](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/state.py): `backend2/app/graph/state.py`
- [LLM provider client](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/llm.py): `backend2/app/graph/llm.py`

### Evidence and evaluation

- [Evidence linking](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/graph/nodes/evidence.py): `backend2/app/graph/nodes/evidence.py`
- [Evidence matching](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/eval/evidence.py): `backend2/app/eval/evidence.py`
- [Run evaluation](https://github.com/snehilsaxena29/scholar-agent/blob/main/backend2/app/eval/metrics.py): `backend2/app/eval/metrics.py`

### Other components

- **Researcher**
- **Supabase auth**
- **Academic paper services**
- **Groq**

## Connections

- Researcher → Research form: submits question (evidence: `frontend2/src/pages/Research.jsx`)
- Research form → API client: starts stream (evidence: `frontend2/src/pages/Research.jsx`)
- API client → FastAPI routes: requests research
- FastAPI routes → Research graph: runs graph (evidence: `backend2/app/main.py`)
- FastAPI routes → Research graph: streams updates (evidence: `backend2/app/main.py`)
- Research graph → Librarian: dispatches (evidence: `backend2/app/graph/build.py`)
- Research graph → Skeptic: dispatches (evidence: `backend2/app/graph/build.py`)
- Research graph → Synthesizer: dispatches (evidence: `backend2/app/graph/build.py`)
- Research graph → Supervisor: dispatches (evidence: `backend2/app/graph/build.py`)
- Research graph → Evidence linking: dispatches (evidence: `backend2/app/graph/build.py`)
- Librarian → Paper search: fetches papers (evidence: `backend2/app/graph/nodes/librarian.py`)
- Paper search → Academic paper services: searches
- Librarian → PDF parsing: parses papers (evidence: `backend2/app/graph/nodes/librarian.py`)
- Librarian → Text chunking: chunks text (evidence: `backend2/app/graph/nodes/librarian.py`)
- Librarian → Vector retrieval: indexes and searches (evidence: `backend2/app/graph/nodes/librarian.py`)
- Vector retrieval → Embeddings: uses vectors (evidence: `backend2/app/ingestion/vectorstore.py`)
- Librarian → Research state: updates retrieval state (evidence: `backend2/app/graph/nodes/librarian.py`)
- Skeptic → LLM provider client: gets model (evidence: `backend2/app/graph/nodes/skeptic.py`)
- Synthesizer → LLM provider client: gets model (evidence: `backend2/app/graph/nodes/synthesizer.py`)
- Supervisor → LLM provider client: gets model (evidence: `backend2/app/graph/nodes/supervisor.py`)
- LLM provider client → Groq: invokes model
- Research graph → Research state: passes state (evidence: `backend2/app/graph/build.py`)
- Supervisor → Synthesizer: retries draft (evidence: `backend2/app/graph/build.py`)
- Evidence linking → Evidence matching: matches passages (evidence: `backend2/app/graph/nodes/evidence.py`)
- FastAPI routes → Run evaluation: scores run (evidence: `backend2/app/main.py`)
- Run evaluation → LLM provider client: judges with model (evidence: `backend2/app/eval/metrics.py`)
- Run evaluation → Embeddings: compares vectors (evidence: `backend2/app/eval/metrics.py`)
- FastAPI routes → Session database: reads and saves history (evidence: `backend2/app/main.py`)
- Research form → Agent trace: renders progress (evidence: `frontend2/src/pages/Research.jsx`)
- Research form → Report display: renders result (evidence: `frontend2/src/pages/Research.jsx`)
- Report display → Report annotations: renders draft (evidence: `frontend2/src/components/ReportView.jsx`)
- Report display → Evidence view: renders evidence (evidence: `frontend2/src/components/ReportView.jsx`)
- Research form → Report export: offers export (evidence: `frontend2/src/pages/Research.jsx`)
- Auth context → Supabase auth: gets auth session (evidence: `frontend2/src/lib/AuthContext.jsx`)
- Research history → Auth context: reads session (evidence: `frontend2/src/pages/History.jsx`)
- Research history → API client: loads history (evidence: `frontend2/src/pages/History.jsx`)
- Research form → API client: saves signed-in run (evidence: `frontend2/src/pages/Research.jsx`)
