# zebir-sir/agentic-rag-paper-assistant architecture

> Architecture diagram of the GitHub repository zebir-sir/agentic-rag-paper-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zebir-sir/agentic-rag-paper-assistant
- Repository: https://github.com/zebir-sir/agentic-rag-paper-assistant

## Overview

PaperWeave is a personal research-paper knowledge space. Researchers import PDFs into a durable queue, then read and annotate papers, explore a relationship graph, or ask evidence-grounded questions through the React workspace. The README documents ingestion, multi-source retrieval, answer review, memory, and reader capabilities; source excerpts and the SOURCE INDEX support selected implementation links. Several subsystems were not sampled, so their documented relationships are cited to the README rather than presented as inspected implementation details.

Main entry points: [`agent/agent_langgraph.py`](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/agent_langgraph.py) (Research workflow), [`ingestion/ingest.py`](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/ingest.py) (Ingest and embed), [`agent/api.py`](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/api.py) (FastAPI service), [`agent/ingestion_jobs.py`](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/ingestion_jobs.py) (Ingestion tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Research workspace"]
  node_workspace["React workspace<br/>[App.jsx]"]
  node_reader["PDF reader<br/>[Reader.jsx]"]
  node_papergraph["Knowledge star map<br/>[PaperGraph.jsx]"]
  node_webapi["API client<br/>[api.js]"]
end

subgraph group_ingestion["Paper ingestion"]
  node_ingest_jobs["Ingestion tasks<br/>[ingestion_jobs.py]"]
  node_task_store[("Task queue state")]
  node_rabbitmq["RabbitMQ queue"]
  node_worker["Ingestion worker"]
  node_parser["PDF extraction<br/>[extract_files.py]"]
  node_chunker["Section chunking<br/>[chunker.py]"]
  node_vision["Figure analysis<br/>[vision_client.py]"]
  node_ingest_runtime["Ingest and embed<br/>[ingest.py]"]
end

subgraph group_research["Research assistant"]
  node_api["FastAPI service<br/>[api.py]"]
  node_planner["Intent and source planning<br/>[intent_planner.py]"]
  node_workflow["Research workflow<br/>[agent_langgraph.py]"]
  node_retrieval["Retrieval tools<br/>[tools.py]"]
  node_answer_review["Evidence review"]
end

subgraph group_knowledge["Knowledge services"]
  node_evidence_store[("Paper evidence store<br/>[db_utils.py]")]
  node_graph_runtime["Relationship runtime<br/>[graph_runtime.py]"]
end

subgraph group_memory["Conversation memory"]
  node_memory_runtime["Memory runtime<br/>[memory_utils.py]"]
  node_session_store[("Conversation records<br/>[db_utils.py]")]
end

node_researcher(("Researcher"))
node_openalex{{"OpenAlex"}}
node_web_search{{"Web search"}}

node_researcher -->|"uses"| node_workspace
node_workspace -->|"calls"| node_webapi
node_reader -->|"calls"| node_webapi
node_papergraph -.->|"uses"| node_webapi
node_webapi -->|"requests"| node_api
node_api -->|"submits PDFs"| node_ingest_jobs
node_ingest_jobs -->|"creates tasks"| node_task_store
node_ingest_jobs -->|"enqueues"| node_rabbitmq
node_rabbitmq -.->|"dispatches"| node_worker
node_worker -->|"executes tasks"| node_ingest_jobs
node_worker -->|"runs ingestion"| node_ingest_runtime
node_ingest_runtime -->|"extracts PDF"| node_parser
node_ingest_runtime -->|"builds chunks"| node_chunker
node_ingest_runtime -->|"analyzes figures"| node_vision
node_ingest_runtime -->|"persists evidence"| node_evidence_store
node_ingest_runtime -->|"refreshes graph"| node_graph_runtime
node_api -.->|"plans questions"| node_planner
node_planner -->|"selects sources"| node_workflow
node_workflow -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"searches papers"| node_evidence_store
node_workflow -->|"expands candidates"| node_graph_runtime
node_graph_runtime -.->|"reads relationships"| node_evidence_store
node_workflow -->|"searches metadata"| node_openalex
node_workflow -.->|"searches web"| node_web_search
node_workflow -->|"reviews evidence"| node_answer_review
node_answer_review -.->|"returns answer"| node_workspace
node_reader -.->|"requests reading"| node_api
node_api -.->|"loads paper data"| node_evidence_store
node_api -.->|"uses memory"| node_memory_runtime
node_memory_runtime -.->|"reads and writes"| node_session_store
node_workflow -.->|"stores messages"| node_session_store

click node_workspace "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/web/src/App.jsx"
click node_reader "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/web/src/Reader.jsx"
click node_papergraph "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/web/src/PaperGraph.jsx"
click node_webapi "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/web/src/api.js"
click node_api "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/api.py"
click node_ingest_jobs "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/ingestion_jobs.py"
click node_task_store "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/ingestion_tasks_db.py"
click node_rabbitmq "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/rabbitmq_producer.py"
click node_worker "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/ingestion_worker.py"
click node_parser "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/extract_files.py"
click node_chunker "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/chunker.py"
click node_vision "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/vision_client.py"
click node_ingest_runtime "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/ingest.py"
click node_evidence_store "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/db_utils.py"
click node_planner "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/intent_planner.py"
click node_workflow "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/agent_langgraph.py"
click node_retrieval "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/tools.py"
click node_graph_runtime "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/graph_runtime.py"
click node_answer_review "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/answer_review_runtime.py"
click node_memory_runtime "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/memory_utils.py"
click node_session_store "https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/db_utils.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_reader,node_papergraph,node_webapi toneBlue
class node_ingest_jobs,node_task_store,node_rabbitmq,node_worker,node_parser,node_chunker,node_vision,node_ingest_runtime toneAmber
class node_api,node_planner,node_workflow,node_retrieval,node_answer_review toneMint
class node_evidence_store,node_graph_runtime toneRose
class node_memory_runtime,node_session_store,node_researcher,node_openalex,node_web_search toneIndigo
```

## Components

### Research workspace

- [React workspace](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [PDF reader](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/web/src/Reader.jsx): `web/src/Reader.jsx`
- [Knowledge star map](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/web/src/PaperGraph.jsx): `web/src/PaperGraph.jsx`
- [API client](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/web/src/api.js): `web/src/api.js`

### Paper ingestion

- [Ingestion tasks](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/ingestion_jobs.py): `agent/ingestion_jobs.py`
- [Task queue state](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/ingestion_tasks_db.py): `agent/ingestion_tasks_db.py`
- [RabbitMQ queue](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/rabbitmq_producer.py): `agent/rabbitmq_producer.py`
- [Ingestion worker](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/ingestion_worker.py): `agent/ingestion_worker.py`
- [PDF extraction](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/extract_files.py): `ingestion/extract_files.py`
- [Section chunking](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/chunker.py): `ingestion/chunker.py`
- [Figure analysis](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/vision_client.py): `ingestion/vision_client.py`
- [Ingest and embed](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/ingestion/ingest.py): `ingestion/ingest.py`

### Research assistant

- [FastAPI service](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/api.py): `agent/api.py`
- [Intent and source planning](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/intent_planner.py): `agent/intent_planner.py`
- [Research workflow](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/agent_langgraph.py): `agent/agent_langgraph.py`
- [Retrieval tools](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/tools.py): `agent/tools.py`
- [Evidence review](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/answer_review_runtime.py): `agent/answer_review_runtime.py`

### Knowledge services

- [Paper evidence store](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/db_utils.py): `agent/db_utils.py`
- [Relationship runtime](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/graph_runtime.py): `agent/graph_runtime.py`

### Conversation memory

- [Memory runtime](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/memory_utils.py): `agent/memory_utils.py`
- [Conversation records](https://github.com/zebir-sir/agentic-rag-paper-assistant/blob/main/agent/db_utils.py): `agent/db_utils.py`

### Other components

- **Researcher**
- **OpenAlex**
- **Web search**

## Connections

- Researcher → React workspace: uses (evidence: `README.md`)
- React workspace → API client: calls (evidence: `web/src/App.jsx`)
- PDF reader → API client: calls (evidence: `web/src/Reader.jsx`)
- Knowledge star map → API client: uses (evidence: `README.md`)
- API client → FastAPI service: requests (evidence: `README.md`)
- FastAPI service → Ingestion tasks: submits PDFs (evidence: `README.md`)
- Ingestion tasks → Task queue state: creates tasks (evidence: `agent/ingestion_jobs.py`)
- Ingestion tasks → RabbitMQ queue: enqueues (evidence: `agent/ingestion_jobs.py`)
- RabbitMQ queue → Ingestion worker: dispatches (evidence: `README.md`)
- Ingestion worker → Ingestion tasks: executes tasks (evidence: `agent/ingestion_worker.py`)
- Ingestion worker → Ingest and embed: runs ingestion (evidence: `agent/ingestion_worker.py`)
- Ingest and embed → PDF extraction: extracts PDF (evidence: `ingestion/ingest.py`)
- Ingest and embed → Section chunking: builds chunks (evidence: `ingestion/ingest.py`)
- Ingest and embed → Figure analysis: analyzes figures (evidence: `ingestion/ingest.py`)
- Ingest and embed → Paper evidence store: persists evidence (evidence: `ingestion/ingest.py`)
- Ingest and embed → Relationship runtime: refreshes graph (evidence: `ingestion/ingest.py`)
- FastAPI service → Intent and source planning: plans questions (evidence: `README.md`)
- Intent and source planning → Research workflow: selects sources (evidence: `README.md`)
- Research workflow → Retrieval tools: retrieves evidence (evidence: `agent/agent_langgraph.py`)
- Retrieval tools → Paper evidence store: searches papers (evidence: `agent/tools.py`)
- Research workflow → Relationship runtime: expands candidates (evidence: `README.md`)
- Relationship runtime → Paper evidence store: reads relationships (evidence: `README.md`)
- Research workflow → OpenAlex: searches metadata (evidence: `README.md`)
- Research workflow → Web search: searches web (evidence: `README.md`)
- Research workflow → Evidence review: reviews evidence (evidence: `README.md`)
- Evidence review → React workspace: returns answer (evidence: `README.md`)
- PDF reader → FastAPI service: requests reading (evidence: `README.md`)
- FastAPI service → Paper evidence store: loads paper data (evidence: `README.md`)
- FastAPI service → Memory runtime: uses memory (evidence: `README.md`)
- Memory runtime → Conversation records: reads and writes (evidence: `README.md`)
- Research workflow → Conversation records: stores messages (evidence: `README.md`)
