# vasanthraj13/ai-research-assistant architecture

> Architecture diagram of the GitHub repository vasanthraj13/ai-research-assistant, 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/vasanthraj13/ai-research-assistant
- Repository: https://github.com/vasanthraj13/ai-research-assistant

## Overview

AI Research Assistant is a web workspace for uploading research papers and running evidence-grounded academic analyses. The principal workflow is upload, extract and index papers, select/search the library, request an answer or analysis, then review the result. The README also documents summaries, comparisons, literature reviews, methodology and gap analysis, contradictions, visual/equation signals, idea generation, and knowledge graphs. Sampled code confirms frontend routing, upload and RAG calls, retrieval, answer generation, and citation handling; unsampled academic features are represented at their documented API boundary.

Main entry points: [`backend/routes/upload.py`](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/upload.py) (Upload endpoint), [`backend/services/document_store.py`](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/document_store.py) (Document store), [`backend/app.py`](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/app.py) (API application), [`frontend/pages/HomePage.jsx`](https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/pages/HomePage.jsx) (Paper library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Research workspace"]
  node_workspace["Workspace shell<br/>[App.jsx]"]
  node_upload_ui["PDF upload<br/>[UploadPanel.jsx]"]
  node_library_ui["Paper library<br/>[HomePage.jsx]"]
  node_result_ui["Analysis results<br/>[ResultPage.jsx]"]
end

subgraph group_api["Flask API"]
  node_flask["API application<br/>[app.py]"]
  node_upload_route["Upload endpoint<br/>[upload.py]"]
  node_documents_route["Document search<br/>[documents.py]"]
  node_rag_route["Question endpoint<br/>[rag.py]"]
  node_academic_route["Academic endpoints<br/>[academic.py]"]
end

subgraph group_processing["Document intelligence"]
  node_pdf["PDF extraction<br/>[pdf_loader.py]"]
  node_chunking["Text chunking<br/>[chunking.py]"]
  node_embedding["Embedding<br/>[embedding.py]"]
  node_rag_pipeline["RAG orchestration<br/>[rag_pipeline.py]"]
  node_retriever["Passage retrieval<br/>[retriever.py]"]
  node_answer["Answer generation<br/>[llm.py]"]
  node_academic_analysis["Academic analysis"]
end

subgraph group_state["Persistence and identity"]
  node_document_store[("Document store<br/>[document_store.py]")]
  node_auth["Authentication service<br/>[auth_service.py]"]
  node_sqlite[("Local document database<br/>[document_store.py]")]
end

node_researcher(("Researcher"))
node_mongo[("MongoDB")]
node_openai["OpenAI"]

node_researcher -->|"uses"| node_workspace
node_workspace -->|"offers upload"| node_upload_ui
node_workspace -->|"opens workspace"| node_library_ui
node_library_ui -->|"opens result"| node_result_ui
node_upload_ui -->|"sends files"| node_upload_route
node_library_ui -->|"searches papers"| node_documents_route
node_library_ui -->|"asks question"| node_rag_route
node_library_ui -->|"requests analysis"| node_academic_route
node_flask -->|"dispatches"| node_upload_route
node_flask -->|"dispatches"| node_documents_route
node_flask -->|"dispatches"| node_rag_route
node_flask -->|"dispatches"| node_academic_route
node_upload_route -->|"extracts text"| node_pdf
node_upload_route -->|"chunks text"| node_chunking
node_upload_route -->|"creates vectors"| node_embedding
node_upload_route -->|"indexes papers"| node_document_store
node_documents_route -->|"searches papers"| node_document_store
node_rag_route -->|"runs query"| node_rag_pipeline
node_rag_pipeline -->|"loads chunks"| node_document_store
node_rag_pipeline -->|"ranks passages"| node_retriever
node_retriever -->|"embeds query"| node_embedding
node_rag_pipeline -->|"generates answer"| node_answer
node_rag_pipeline -->|"saves conversation"| node_document_store
node_academic_route -->|"runs analyses"| node_academic_analysis
node_academic_analysis -->|"reads papers"| node_document_store
node_document_store -->|"reads and writes"| node_sqlite
node_flask -->|"authenticates users"| node_auth
node_auth -.->|"uses when available"| node_mongo
node_answer -.->|"generates with"| node_openai

click node_workspace "https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/App.jsx"
click node_upload_ui "https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/components/UploadPanel.jsx"
click node_library_ui "https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/pages/HomePage.jsx"
click node_result_ui "https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/pages/ResultPage.jsx"
click node_flask "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/app.py"
click node_upload_route "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/upload.py"
click node_documents_route "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/documents.py"
click node_rag_route "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/rag.py"
click node_academic_route "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/academic.py"
click node_pdf "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/pdf_loader.py"
click node_chunking "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/chunking.py"
click node_embedding "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/embedding.py"
click node_rag_pipeline "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/rag_pipeline.py"
click node_retriever "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/retriever.py"
click node_answer "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/llm.py"
click node_academic_analysis "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/academic_analysis.py"
click node_document_store "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/document_store.py"
click node_auth "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/auth_service.py"
click node_sqlite "https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/document_store.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_workspace,node_upload_ui,node_library_ui,node_result_ui toneBlue
class node_flask,node_upload_route,node_documents_route,node_rag_route,node_academic_route,node_mongo toneAmber
class node_pdf,node_chunking,node_embedding,node_rag_pipeline,node_retriever,node_answer,node_academic_analysis toneMint
class node_document_store,node_auth,node_sqlite toneRose
class node_researcher,node_openai toneIndigo
```

## Components

### Research workspace

- [Workspace shell](https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/App.jsx): `frontend/App.jsx`
- [PDF upload](https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/components/UploadPanel.jsx): `frontend/components/UploadPanel.jsx`
- [Paper library](https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/pages/HomePage.jsx): `frontend/pages/HomePage.jsx`
- [Analysis results](https://github.com/vasanthraj13/ai-research-assistant/blob/main/frontend/pages/ResultPage.jsx): `frontend/pages/ResultPage.jsx`

### Flask API

- [API application](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/app.py): `backend/app.py`
- [Upload endpoint](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/upload.py): `backend/routes/upload.py`
- [Document search](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/documents.py): `backend/routes/documents.py`
- [Question endpoint](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/rag.py): `backend/routes/rag.py`
- [Academic endpoints](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/routes/academic.py): `backend/routes/academic.py`

### Document intelligence

- [PDF extraction](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/pdf_loader.py): `backend/services/pdf_loader.py`
- [Text chunking](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/chunking.py): `backend/services/chunking.py`
- [Embedding](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/embedding.py): `backend/services/embedding.py`
- [RAG orchestration](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/rag_pipeline.py): `backend/services/rag_pipeline.py`
- [Passage retrieval](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/retriever.py): `backend/services/retriever.py`
- [Answer generation](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/llm.py): `backend/services/llm.py`
- [Academic analysis](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/academic_analysis.py): `backend/services/academic_analysis.py`

### Persistence and identity

- [Document store](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/document_store.py): `backend/services/document_store.py`
- [Authentication service](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [Local document database](https://github.com/vasanthraj13/ai-research-assistant/blob/main/backend/services/document_store.py): `backend/services/document_store.py`

### Other components

- **Researcher**
- **MongoDB**
- **OpenAI**

## Connections

- Researcher → Workspace shell: uses
- Workspace shell → PDF upload: offers upload
- Workspace shell → Paper library: opens workspace
- Paper library → Analysis results: opens result
- PDF upload → Upload endpoint: sends files
- Paper library → Document search: searches papers
- Paper library → Question endpoint: asks question
- Paper library → Academic endpoints: requests analysis
- API application → Upload endpoint: dispatches
- API application → Document search: dispatches
- API application → Question endpoint: dispatches
- API application → Academic endpoints: dispatches
- Upload endpoint → PDF extraction: extracts text
- Upload endpoint → Text chunking: chunks text
- Upload endpoint → Embedding: creates vectors
- Upload endpoint → Document store: indexes papers
- Document search → Document store: searches papers
- Question endpoint → RAG orchestration: runs query
- RAG orchestration → Document store: loads chunks
- RAG orchestration → Passage retrieval: ranks passages
- Passage retrieval → Embedding: embeds query
- RAG orchestration → Answer generation: generates answer
- RAG orchestration → Document store: saves conversation
- Academic endpoints → Academic analysis: runs analyses
- Academic analysis → Document store: reads papers
- Document store → Local document database: reads and writes
- API application → Authentication service: authenticates users
- Authentication service → MongoDB: uses when available
- Answer generation → OpenAI: generates with