# miteshgupta07/researchmate architecture

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

- Interactive diagram: https://gitdiagram.com/miteshgupta07/researchmate
- Repository: https://github.com/miteshgupta07/researchmate

## Overview

ResearchMate is a Streamlit research assistant backed by a FastAPI service. Researchers upload PDFs, then ask questions; the UI sends requests to backend routes, which use document retrieval, an LLM, and persistent conversation history to produce grounded answers. Separate capabilities include agent-based research, portfolio Q&A, and RAG evaluation. The excerpts show RAG request handling and several orchestration links; other route internals are unsampled, so their relationships are limited to documented features and visible wiring.

Main entry points: [`backend/main.py`](https://github.com/miteshgupta07/researchmate/blob/main/backend/main.py) (API application), [`backend/api/rag.py`](https://github.com/miteshgupta07/researchmate/blob/main/backend/api/rag.py) (RAG query route), [`eval/run_eval.py`](https://github.com/miteshgupta07/researchmate/blob/main/eval/run_eval.py) (Evaluation runner), [`views/chat.py`](https://github.com/miteshgupta07/researchmate/blob/main/views/chat.py) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Research interface"]
  node_chat_view["Chat interface<br/>[chat.py]"]
  node_api_client["API client<br/>[api_client.py]"]
  node_css["UI styling<br/>[css.py]"]
end

subgraph group_api["Backend API"]
  node_api_entry["API application<br/>[main.py]"]
  node_chat_api["Chat routes<br/>[chat.py]"]
  node_document_api["Document routes<br/>[documents.py]"]
  node_history_api["History routes<br/>[history.py]"]
  node_rag_api["RAG query route<br/>[rag.py]"]
  node_agent_api["Agent route<br/>[agent.py]"]
  node_portfolio_api["Portfolio chat<br/>[portfolio.py]"]
end

subgraph group_services["Research services"]
  node_deps["Dependency wiring<br/>[deps.py]"]
  node_rag_pipeline["Document RAG<br/>[pipeline.py]"]
  node_portfolio_rag["Portfolio retrieval<br/>[portfolio.py]"]
  node_llm_service["LLM service<br/>[service.py]"]
  node_history_store["History store<br/>[postgres.py]"]
  node_history_base["History interface<br/>[base.py]"]
end

subgraph group_evaluation["RAG evaluation"]
  node_eval_runner["Evaluation runner<br/>[run_eval.py]"]
  node_dataset_loader["Benchmark loader<br/>[load_dataset.py]"]
  node_metrics["RAG metrics<br/>[metrics.py]"]
end

node_researcher(("Researcher"))
node_postgres[("PostgreSQL")]
node_faiss[("FAISS indexes")]
node_arxiv["arXiv search"]

node_researcher -->|"uses"| node_chat_view
node_chat_view -->|"sends requests"| node_api_client
node_chat_view -->|"renders with"| node_css
node_api_client -->|"calls API"| node_api_entry
node_api_entry -->|"mounts"| node_chat_api
node_api_entry -->|"mounts"| node_rag_api
node_api_entry -->|"mounts"| node_document_api
node_api_entry -->|"mounts"| node_history_api
node_api_entry -->|"mounts"| node_agent_api
node_api_entry -->|"mounts"| node_portfolio_api
node_rag_api -->|"loads and queries"| node_rag_pipeline
node_rag_api -->|"gets model"| node_deps
node_deps -->|"selects model"| node_llm_service
node_rag_api -->|"reads and writes"| node_history_store
node_history_store -->|"implements"| node_history_base
node_history_store -->|"persists history"| node_postgres
node_rag_pipeline -->|"stores and retrieves"| node_faiss
node_document_api -.->|"ingests PDFs"| node_rag_pipeline
node_agent_api -->|"searches papers"| node_arxiv
node_portfolio_api -.->|"uses retrieval"| node_portfolio_rag
node_eval_runner -->|"loads benchmark"| node_dataset_loader
node_eval_runner -->|"computes metrics"| node_metrics
node_eval_runner -->|"uses model"| node_llm_service

click node_chat_view "https://github.com/miteshgupta07/researchmate/blob/main/views/chat.py"
click node_api_client "https://github.com/miteshgupta07/researchmate/blob/main/frontend/api_client.py"
click node_css "https://github.com/miteshgupta07/researchmate/blob/main/frontend/css.py"
click node_api_entry "https://github.com/miteshgupta07/researchmate/blob/main/backend/main.py"
click node_chat_api "https://github.com/miteshgupta07/researchmate/blob/main/backend/api/chat.py"
click node_document_api "https://github.com/miteshgupta07/researchmate/blob/main/backend/api/documents.py"
click node_history_api "https://github.com/miteshgupta07/researchmate/blob/main/backend/api/history.py"
click node_rag_api "https://github.com/miteshgupta07/researchmate/blob/main/backend/api/rag.py"
click node_agent_api "https://github.com/miteshgupta07/researchmate/blob/main/backend/api/agent.py"
click node_portfolio_api "https://github.com/miteshgupta07/researchmate/blob/main/backend/api/portfolio.py"
click node_deps "https://github.com/miteshgupta07/researchmate/blob/main/backend/core/deps.py"
click node_rag_pipeline "https://github.com/miteshgupta07/researchmate/blob/main/backend/core/rag/pipeline.py"
click node_portfolio_rag "https://github.com/miteshgupta07/researchmate/blob/main/backend/core/rag/portfolio.py"
click node_llm_service "https://github.com/miteshgupta07/researchmate/blob/main/backend/core/llm/service.py"
click node_history_store "https://github.com/miteshgupta07/researchmate/blob/main/backend/core/chat_history/postgres.py"
click node_history_base "https://github.com/miteshgupta07/researchmate/blob/main/backend/core/chat_history/base.py"
click node_eval_runner "https://github.com/miteshgupta07/researchmate/blob/main/eval/run_eval.py"
click node_dataset_loader "https://github.com/miteshgupta07/researchmate/blob/main/eval/load_dataset.py"
click node_metrics "https://github.com/miteshgupta07/researchmate/blob/main/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_chat_view,node_api_client,node_css toneBlue
class node_api_entry,node_chat_api,node_document_api,node_history_api,node_rag_api,node_agent_api,node_portfolio_api,node_postgres,node_faiss toneAmber
class node_deps,node_rag_pipeline,node_portfolio_rag,node_llm_service,node_history_store,node_history_base toneMint
class node_eval_runner,node_dataset_loader,node_metrics toneRose
class node_researcher,node_arxiv toneIndigo
```

## Components

### Research interface

- [Chat interface](https://github.com/miteshgupta07/researchmate/blob/main/views/chat.py): `views/chat.py`
- [API client](https://github.com/miteshgupta07/researchmate/blob/main/frontend/api_client.py): `frontend/api_client.py`
- [UI styling](https://github.com/miteshgupta07/researchmate/blob/main/frontend/css.py): `frontend/css.py`

### Backend API

- [API application](https://github.com/miteshgupta07/researchmate/blob/main/backend/main.py): `backend/main.py`
- [Chat routes](https://github.com/miteshgupta07/researchmate/blob/main/backend/api/chat.py): `backend/api/chat.py`
- [Document routes](https://github.com/miteshgupta07/researchmate/blob/main/backend/api/documents.py): `backend/api/documents.py`
- [History routes](https://github.com/miteshgupta07/researchmate/blob/main/backend/api/history.py): `backend/api/history.py`
- [RAG query route](https://github.com/miteshgupta07/researchmate/blob/main/backend/api/rag.py): `backend/api/rag.py`
- [Agent route](https://github.com/miteshgupta07/researchmate/blob/main/backend/api/agent.py): `backend/api/agent.py`
- [Portfolio chat](https://github.com/miteshgupta07/researchmate/blob/main/backend/api/portfolio.py): `backend/api/portfolio.py`

### Research services

- [Dependency wiring](https://github.com/miteshgupta07/researchmate/blob/main/backend/core/deps.py): `backend/core/deps.py`
- [Document RAG](https://github.com/miteshgupta07/researchmate/blob/main/backend/core/rag/pipeline.py): `backend/core/rag/pipeline.py`
- [Portfolio retrieval](https://github.com/miteshgupta07/researchmate/blob/main/backend/core/rag/portfolio.py): `backend/core/rag/portfolio.py`
- [LLM service](https://github.com/miteshgupta07/researchmate/blob/main/backend/core/llm/service.py): `backend/core/llm/service.py`
- [History store](https://github.com/miteshgupta07/researchmate/blob/main/backend/core/chat_history/postgres.py): `backend/core/chat_history/postgres.py`
- [History interface](https://github.com/miteshgupta07/researchmate/blob/main/backend/core/chat_history/base.py): `backend/core/chat_history/base.py`

### RAG evaluation

- [Evaluation runner](https://github.com/miteshgupta07/researchmate/blob/main/eval/run_eval.py): `eval/run_eval.py`
- [Benchmark loader](https://github.com/miteshgupta07/researchmate/blob/main/eval/load_dataset.py): `eval/load_dataset.py`
- [RAG metrics](https://github.com/miteshgupta07/researchmate/blob/main/eval/metrics.py): `eval/metrics.py`

### Other components

- **Researcher**
- **PostgreSQL**
- **FAISS indexes**
- **arXiv search**

## Connections

- Researcher → Chat interface: uses
- Chat interface → API client: sends requests (evidence: `views/chat.py`)
- Chat interface → UI styling: renders with (evidence: `views/chat.py`)
- API client → API application: calls API
- API application → Chat routes: mounts (evidence: `backend/main.py`)
- API application → RAG query route: mounts (evidence: `backend/main.py`)
- API application → Document routes: mounts (evidence: `backend/main.py`)
- API application → History routes: mounts (evidence: `backend/main.py`)
- API application → Agent route: mounts (evidence: `backend/main.py`)
- API application → Portfolio chat: mounts (evidence: `backend/main.py`)
- RAG query route → Document RAG: loads and queries (evidence: `backend/api/rag.py`)
- RAG query route → Dependency wiring: gets model (evidence: `backend/api/rag.py`)
- Dependency wiring → LLM service: selects model (evidence: `backend/core/deps.py`)
- RAG query route → History store: reads and writes (evidence: `backend/api/rag.py`)
- History store → History interface: implements (evidence: `backend/core/chat_history/postgres.py`)
- History store → PostgreSQL: persists history
- Document RAG → FAISS indexes: stores and retrieves (evidence: `backend/core/rag/pipeline.py`)
- Document routes → Document RAG: ingests PDFs
- Agent route → arXiv search: searches papers (evidence: `backend/api/agent.py`)
- Portfolio chat → Portfolio retrieval: uses retrieval
- Evaluation runner → Benchmark loader: loads benchmark (evidence: `eval/run_eval.py`)
- Evaluation runner → RAG metrics: computes metrics (evidence: `eval/run_eval.py`)
- Evaluation runner → LLM service: uses model (evidence: `eval/run_eval.py`)
