# tswoen/paper-agent architecture

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

- Interactive diagram: https://gitdiagram.com/tswoen/paper-agent
- Repository: https://github.com/tswoen/paper-agent

## Overview

Paper-Agent is a research-assistant workbench that turns a research topic into a traceable literature review. The principal workflow runs from session submission through search planning, multi-source retrieval, relevance reading and full-text indexing, layered analysis, outlining, and evidence-based section writing. The Vue workbench presents progress and results over an API/SSE session runtime; settings provide model and embedding configuration. The README documents these product stages and capabilities; some subsystem links below are therefore cited to it rather than inferred from unsampled implementations.

Main entry points: [`src/graph/runtime.py`](https://github.com/tswoen/paper-agent/blob/main/src/graph/runtime.py) (Workflow Runtime), [`src/graph/read_node.py`](https://github.com/tswoen/paper-agent/blob/main/src/graph/read_node.py) (Relevance Reading), [`src/services/session_runs.py`](https://github.com/tswoen/paper-agent/blob/main/src/services/session_runs.py) (Run Service), [`src/llm/base.py`](https://github.com/tswoen/paper-agent/blob/main/src/llm/base.py) (LLM Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Research Workbench"]
  node_workspace["Session Workbench"]
  node_composer["Topic Composer"]
  node_streamui["Progress Timeline"]
  node_settingsui["Model Settings"]
end

subgraph group_session["Sessions and Runtime"]
  node_sessionapi["Session API<br/>[sessions.py]"]
  node_runs["Run Service<br/>[session_runs.py]"]
  node_workflow["Workflow Runtime<br/>[runtime.py]"]
  node_sessionstore[("Session Store<br/>[sqlite.py]")]
end

subgraph group_research["Research Workflow"]
  node_searchplan["Search Planning<br/>[searchAgent.py]"]
  node_reading["Relevance Reading<br/>[read_node.py]"]
  node_analysis["Research Analysis<br/>[analyse_node.py]"]
  node_outline["Evidence Outline"]
  node_writing["Review Writing<br/>[writing_node.py]"]
end

subgraph group_knowledge["Sources and Indexing"]
  node_retrieval["Paper Retrieval<br/>[service.py]"]
  node_connectors["Source Connectors"]
  node_fulltext["Full-text Processing<br/>[read_fulltext.py]"]
  node_chunking["Text Chunking<br/>[chunkers.py]"]
  node_vectorstore[("Paper Vector Store")]
end

subgraph group_models["Models and Settings"]
  node_llm["LLM Providers<br/>[base.py]"]
  node_settingsapi["Settings Service<br/>[settings.py]"]
  node_settingsstore[("Settings Repository<br/>[json.py]")]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_workspace
node_workspace -->|"renders"| node_composer
node_composer -->|"submits topic"| node_sessionapi
node_sessionapi -->|"starts run"| node_runs
node_runs -->|"executes"| node_workflow
node_runs -->|"persists events"| node_sessionstore
node_runs -->|"streams progress"| node_streamui
node_workflow -->|"plans search"| node_searchplan
node_searchplan -->|"provides search intent"| node_retrieval
node_retrieval -->|"queries sources"| node_connectors
node_connectors -->|"returns papers"| node_reading
node_workflow -->|"runs reading"| node_reading
node_reading -->|"processes selected papers"| node_fulltext
node_fulltext -->|"chunks text"| node_chunking
node_reading -->|"indexes papers"| node_vectorstore
node_workflow -->|"runs analysis"| node_analysis
node_workflow -->|"generates outline"| node_outline
node_workflow -->|"writes review"| node_writing
node_searchplan -->|"generates plan"| node_llm
node_reading -->|"assesses relevance"| node_llm
node_writing -->|"generates sections"| node_llm
node_settingsui -->|"configures models"| node_settingsapi
node_settingsapi -->|"reads and saves"| node_settingsstore
node_settingsstore -->|"supplies configuration"| node_llm

click node_workspace "https://github.com/tswoen/paper-agent/blob/main/front/src/views/SessionWorkspaceView.vue"
click node_composer "https://github.com/tswoen/paper-agent/blob/main/front/src/components/session/SessionComposer.vue"
click node_streamui "https://github.com/tswoen/paper-agent/blob/main/front/src/lib/session-stream-aggregator.ts"
click node_settingsui "https://github.com/tswoen/paper-agent/blob/main/front/src/views/SystemSettingsView.vue"
click node_sessionapi "https://github.com/tswoen/paper-agent/blob/main/src/api/routers/sessions.py"
click node_runs "https://github.com/tswoen/paper-agent/blob/main/src/services/session_runs.py"
click node_workflow "https://github.com/tswoen/paper-agent/blob/main/src/graph/runtime.py"
click node_sessionstore "https://github.com/tswoen/paper-agent/blob/main/src/repositories/sessions/sqlite.py"
click node_searchplan "https://github.com/tswoen/paper-agent/blob/main/src/agents/searchAgent.py"
click node_retrieval "https://github.com/tswoen/paper-agent/blob/main/src/paper_retrieval/service.py"
click node_connectors "https://github.com/tswoen/paper-agent/tree/main/src/paper_retrieval/connectors"
click node_reading "https://github.com/tswoen/paper-agent/blob/main/src/graph/read_node.py"
click node_fulltext "https://github.com/tswoen/paper-agent/blob/main/src/utils/read_utils/read_fulltext.py"
click node_chunking "https://github.com/tswoen/paper-agent/blob/main/src/utils/read_utils/chunkers.py"
click node_vectorstore "https://github.com/tswoen/paper-agent/blob/main/src/repositories/chroma/read_vector_store.py"
click node_analysis "https://github.com/tswoen/paper-agent/blob/main/src/graph/analyse_node.py"
click node_outline "https://github.com/tswoen/paper-agent/blob/main/src/graph/writing_outline_node.py"
click node_writing "https://github.com/tswoen/paper-agent/blob/main/src/graph/writing_node.py"
click node_llm "https://github.com/tswoen/paper-agent/blob/main/src/llm/base.py"
click node_settingsapi "https://github.com/tswoen/paper-agent/blob/main/src/services/settings.py"
click node_settingsstore "https://github.com/tswoen/paper-agent/blob/main/src/repositories/settings/json.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_composer,node_streamui,node_settingsui toneBlue
class node_sessionapi,node_runs,node_workflow,node_sessionstore toneAmber
class node_searchplan,node_reading,node_analysis,node_outline,node_writing toneMint
class node_retrieval,node_connectors,node_fulltext,node_chunking,node_vectorstore toneRose
class node_llm,node_settingsapi,node_settingsstore,node_researcher toneIndigo
```

## Components

### Research Workbench

- [Session Workbench](https://github.com/tswoen/paper-agent/blob/main/front/src/views/SessionWorkspaceView.vue): `front/src/views/SessionWorkspaceView.vue`
- [Topic Composer](https://github.com/tswoen/paper-agent/blob/main/front/src/components/session/SessionComposer.vue): `front/src/components/session/SessionComposer.vue`
- [Progress Timeline](https://github.com/tswoen/paper-agent/blob/main/front/src/lib/session-stream-aggregator.ts): `front/src/lib/session-stream-aggregator.ts`
- [Model Settings](https://github.com/tswoen/paper-agent/blob/main/front/src/views/SystemSettingsView.vue): `front/src/views/SystemSettingsView.vue`

### Sessions and Runtime

- [Session API](https://github.com/tswoen/paper-agent/blob/main/src/api/routers/sessions.py): `src/api/routers/sessions.py`
- [Run Service](https://github.com/tswoen/paper-agent/blob/main/src/services/session_runs.py): `src/services/session_runs.py`
- [Workflow Runtime](https://github.com/tswoen/paper-agent/blob/main/src/graph/runtime.py): `src/graph/runtime.py`
- [Session Store](https://github.com/tswoen/paper-agent/blob/main/src/repositories/sessions/sqlite.py): `src/repositories/sessions/sqlite.py`

### Research Workflow

- [Search Planning](https://github.com/tswoen/paper-agent/blob/main/src/agents/searchAgent.py): `src/agents/searchAgent.py`
- [Relevance Reading](https://github.com/tswoen/paper-agent/blob/main/src/graph/read_node.py): `src/graph/read_node.py`
- [Research Analysis](https://github.com/tswoen/paper-agent/blob/main/src/graph/analyse_node.py): `src/graph/analyse_node.py`
- [Evidence Outline](https://github.com/tswoen/paper-agent/blob/main/src/graph/writing_outline_node.py): `src/graph/writing_outline_node.py`
- [Review Writing](https://github.com/tswoen/paper-agent/blob/main/src/graph/writing_node.py): `src/graph/writing_node.py`

### Sources and Indexing

- [Paper Retrieval](https://github.com/tswoen/paper-agent/blob/main/src/paper_retrieval/service.py): `src/paper_retrieval/service.py`
- [Source Connectors](https://github.com/tswoen/paper-agent/tree/main/src/paper_retrieval/connectors): `src/paper_retrieval/connectors`
- [Full-text Processing](https://github.com/tswoen/paper-agent/blob/main/src/utils/read_utils/read_fulltext.py): `src/utils/read_utils/read_fulltext.py`
- [Text Chunking](https://github.com/tswoen/paper-agent/blob/main/src/utils/read_utils/chunkers.py): `src/utils/read_utils/chunkers.py`
- [Paper Vector Store](https://github.com/tswoen/paper-agent/blob/main/src/repositories/chroma/read_vector_store.py): `src/repositories/chroma/read_vector_store.py`

### Models and Settings

- [LLM Providers](https://github.com/tswoen/paper-agent/blob/main/src/llm/base.py): `src/llm/base.py`
- [Settings Service](https://github.com/tswoen/paper-agent/blob/main/src/services/settings.py): `src/services/settings.py`
- [Settings Repository](https://github.com/tswoen/paper-agent/blob/main/src/repositories/settings/json.py): `src/repositories/settings/json.py`

### Other components

- **Researcher**

## Connections

- Researcher → Session Workbench: uses
- Session Workbench → Topic Composer: renders (evidence: `front/src/views/SessionWorkspaceView.vue`)
- Topic Composer → Session API: submits topic
- Session API → Run Service: starts run (evidence: `src/api/routers/sessions.py`)
- Run Service → Workflow Runtime: executes (evidence: `src/services/session_runs.py`)
- Run Service → Session Store: persists events
- Run Service → Progress Timeline: streams progress
- Workflow Runtime → Search Planning: plans search
- Search Planning → Paper Retrieval: provides search intent
- Paper Retrieval → Source Connectors: queries sources (evidence: `src/paper_retrieval/service.py`)
- Source Connectors → Relevance Reading: returns papers
- Workflow Runtime → Relevance Reading: runs reading (evidence: `src/graph/read_node.py`)
- Relevance Reading → Full-text Processing: processes selected papers (evidence: `src/graph/read_node.py`)
- Full-text Processing → Text Chunking: chunks text
- Relevance Reading → Paper Vector Store: indexes papers (evidence: `src/graph/read_node.py`)
- Workflow Runtime → Research Analysis: runs analysis
- Workflow Runtime → Evidence Outline: generates outline
- Workflow Runtime → Review Writing: writes review
- Search Planning → LLM Providers: generates plan (evidence: `src/agents/searchAgent.py`)
- Relevance Reading → LLM Providers: assesses relevance
- Review Writing → LLM Providers: generates sections
- Model Settings → Settings Service: configures models
- Settings Service → Settings Repository: reads and saves
- Settings Repository → LLM Providers: supplies configuration (evidence: `src/repositories/settings/json.py`)