# yutomi141/paper_lens architecture

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

- Interactive diagram: https://gitdiagram.com/yutomi141/paper_lens
- Repository: https://github.com/yutomi141/paper_lens

## Overview

Paper Lens is a local academic-paper reader: users upload and read PDFs, then use AI explanations, translation, and Q&A alongside notes, references, and vocabulary tools. The backend exposes separate paper, AI, and domain-data routes, stores state in SQLite, and uses a local Ollama service for model work. The graph includes documented product capabilities even where their implementation was not sampled; those components have few or no inferred connections. Unsampled source limits evidence for several frontend-to-backend and route relationships.

Main entry points: [`backend/db/database.py`](https://github.com/yutomi141/paper_lens/blob/main/backend/db/database.py) (SQLite Database), [`backend/main.py`](https://github.com/yutomi141/paper_lens/blob/main/backend/main.py) (FastAPI App), [`backend/routers/papers.py`](https://github.com/yutomi141/paper_lens/blob/main/backend/routers/papers.py) (Paper Routes), [`frontend/components/SidePanel.tsx`](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/SidePanel.tsx) (AI Side Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reading["PDF Reading"]
  node_reader["Paper Reader<br/>[&#91;id&#93;.tsx]"]
  node_pdf_viewer["PDF Viewer<br/>[PDFViewer.tsx]"]
  node_selection["Text Selection<br/>[SelectionMenu.tsx]"]
  node_paper_routes["Paper Routes<br/>[papers.py]"]
  node_pdf_extract["PDF Extraction<br/>[pdf_extractor.py]"]
end

subgraph group_ai["AI Assistance"]
  node_ai_panel["AI Side Panel<br/>[SidePanel.tsx]"]
  node_translation_ui["Translation View"]
  node_streaming_text["Streaming Renderer<br/>[StreamingText.tsx]"]
  node_ai_routes["AI Routes<br/>[ai.py]"]
  node_prompt_builder["Prompt Builder<br/>[prompt_manager.py]"]
  node_translation_jobs["Full-Text Translation<br/>[translation_job.py]"]
  node_ollama{{"Local Ollama"}}
end

subgraph group_study["Study Tools"]
  node_chat_ui["Q&amp;A Chat<br/>[ChatPanel.tsx]"]
  node_notes_ui["Notes Panel<br/>[NotePanel.tsx]"]
  node_references_ui["References Panel"]
  node_notes_routes["Notes Routes<br/>[notes.py]"]
  node_chat_routes["Chat Routes<br/>[chat.py]"]
  node_references_routes["Reference Routes<br/>[references.py]"]
  node_words_routes["Vocabulary Routes<br/>[words.py]"]
  node_words_page["Vocabulary Page<br/>[words.tsx]"]
end

subgraph group_platform["Application Core"]
  node_settings_page["Settings Page<br/>[settings.tsx]"]
  node_app["FastAPI App<br/>[main.py]"]
  node_database[("SQLite Database<br/>[database.py]")]
  node_models["Domain Models<br/>[models.py]"]
end

node_user(("Reader"))

node_user -->|"opens"| node_reader
node_user -->|"uploads PDF"| node_paper_routes
node_ai_panel -->|"streams requests"| node_ai_routes
node_ai_panel -->|"renders"| node_translation_ui
node_ai_panel -->|"renders"| node_references_ui
node_ai_panel -->|"renders"| node_notes_ui
node_ai_panel -->|"renders"| node_chat_ui
node_ai_routes -->|"builds prompts"| node_prompt_builder
node_ai_routes -->|"requests generation"| node_ollama
node_paper_routes -->|"extracts PDF text"| node_pdf_extract
node_paper_routes -->|"generates summary"| node_ollama
node_paper_routes -->|"starts jobs"| node_translation_jobs
node_app -->|"registers"| node_paper_routes
node_app -->|"registers"| node_ai_routes
node_app -->|"registers"| node_notes_routes
node_app -->|"registers"| node_chat_routes
node_app -->|"registers"| node_references_routes
node_app -->|"registers"| node_words_routes
node_paper_routes -->|"reads and writes"| node_database
node_ai_routes -->|"reads and writes"| node_database
node_notes_routes -->|"reads and writes"| node_database
node_chat_routes -->|"reads and writes"| node_database
node_references_routes -->|"reads and writes"| node_database
node_words_routes -->|"reads and writes"| node_database
node_translation_jobs -->|"tracks chunks"| node_database
node_translation_jobs -->|"extracts pages"| node_pdf_extract
node_translation_jobs -->|"translates chunks"| node_ollama
node_words_routes -->|"generates meanings"| node_ollama
node_models -->|"uses base"| node_database

click node_reader "https://github.com/yutomi141/paper_lens/blob/main/frontend/pages/reader/%5Bid%5D.tsx"
click node_pdf_viewer "https://github.com/yutomi141/paper_lens/blob/main/frontend/components/PDFViewer.tsx"
click node_selection "https://github.com/yutomi141/paper_lens/blob/main/frontend/components/SelectionMenu.tsx"
click node_paper_routes "https://github.com/yutomi141/paper_lens/blob/main/backend/routers/papers.py"
click node_pdf_extract "https://github.com/yutomi141/paper_lens/blob/main/backend/services/pdf_extractor.py"
click node_ai_panel "https://github.com/yutomi141/paper_lens/blob/main/frontend/components/SidePanel.tsx"
click node_translation_ui "https://github.com/yutomi141/paper_lens/blob/main/frontend/components/TranslationPanel.tsx"
click node_streaming_text "https://github.com/yutomi141/paper_lens/blob/main/frontend/components/StreamingText.tsx"
click node_ai_routes "https://github.com/yutomi141/paper_lens/blob/main/backend/routers/ai.py"
click node_prompt_builder "https://github.com/yutomi141/paper_lens/blob/main/backend/services/prompt_manager.py"
click node_translation_jobs "https://github.com/yutomi141/paper_lens/blob/main/backend/services/translation_job.py"
click node_chat_ui "https://github.com/yutomi141/paper_lens/blob/main/frontend/components/ChatPanel.tsx"
click node_notes_ui "https://github.com/yutomi141/paper_lens/blob/main/frontend/components/NotePanel.tsx"
click node_references_ui "https://github.com/yutomi141/paper_lens/blob/main/frontend/components/ReferencesPanel.tsx"
click node_notes_routes "https://github.com/yutomi141/paper_lens/blob/main/backend/routers/notes.py"
click node_chat_routes "https://github.com/yutomi141/paper_lens/blob/main/backend/routers/chat.py"
click node_references_routes "https://github.com/yutomi141/paper_lens/blob/main/backend/routers/references.py"
click node_words_routes "https://github.com/yutomi141/paper_lens/blob/main/backend/routers/words.py"
click node_words_page "https://github.com/yutomi141/paper_lens/blob/main/frontend/pages/words.tsx"
click node_settings_page "https://github.com/yutomi141/paper_lens/blob/main/frontend/pages/settings.tsx"
click node_app "https://github.com/yutomi141/paper_lens/blob/main/backend/main.py"
click node_database "https://github.com/yutomi141/paper_lens/blob/main/backend/db/database.py"
click node_models "https://github.com/yutomi141/paper_lens/blob/main/backend/db/models.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_reader,node_pdf_viewer,node_selection,node_paper_routes,node_pdf_extract toneBlue
class node_ai_panel,node_translation_ui,node_streaming_text,node_ai_routes,node_prompt_builder,node_translation_jobs,node_ollama toneAmber
class node_chat_ui,node_notes_ui,node_references_ui,node_notes_routes,node_chat_routes,node_references_routes,node_words_routes,node_words_page toneMint
class node_settings_page,node_app,node_database,node_models toneRose
class node_user toneIndigo
```

## Components

### PDF Reading

- [Paper Reader](https://github.com/yutomi141/paper_lens/blob/main/frontend/pages/reader/%5Bid%5D.tsx): `frontend/pages/reader/[id].tsx`
- [PDF Viewer](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/PDFViewer.tsx): `frontend/components/PDFViewer.tsx`
- [Text Selection](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/SelectionMenu.tsx): `frontend/components/SelectionMenu.tsx`
- [Paper Routes](https://github.com/yutomi141/paper_lens/blob/main/backend/routers/papers.py): `backend/routers/papers.py`
- [PDF Extraction](https://github.com/yutomi141/paper_lens/blob/main/backend/services/pdf_extractor.py): `backend/services/pdf_extractor.py`

### AI Assistance

- [AI Side Panel](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/SidePanel.tsx): `frontend/components/SidePanel.tsx`
- [Translation View](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/TranslationPanel.tsx): `frontend/components/TranslationPanel.tsx`
- [Streaming Renderer](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/StreamingText.tsx): `frontend/components/StreamingText.tsx`
- [AI Routes](https://github.com/yutomi141/paper_lens/blob/main/backend/routers/ai.py): `backend/routers/ai.py`
- [Prompt Builder](https://github.com/yutomi141/paper_lens/blob/main/backend/services/prompt_manager.py): `backend/services/prompt_manager.py`
- [Full-Text Translation](https://github.com/yutomi141/paper_lens/blob/main/backend/services/translation_job.py): `backend/services/translation_job.py`
- **Local Ollama**

### Study Tools

- [Q&A Chat](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/ChatPanel.tsx): `frontend/components/ChatPanel.tsx`
- [Notes Panel](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/NotePanel.tsx): `frontend/components/NotePanel.tsx`
- [References Panel](https://github.com/yutomi141/paper_lens/blob/main/frontend/components/ReferencesPanel.tsx): `frontend/components/ReferencesPanel.tsx`
- [Notes Routes](https://github.com/yutomi141/paper_lens/blob/main/backend/routers/notes.py): `backend/routers/notes.py`
- [Chat Routes](https://github.com/yutomi141/paper_lens/blob/main/backend/routers/chat.py): `backend/routers/chat.py`
- [Reference Routes](https://github.com/yutomi141/paper_lens/blob/main/backend/routers/references.py): `backend/routers/references.py`
- [Vocabulary Routes](https://github.com/yutomi141/paper_lens/blob/main/backend/routers/words.py): `backend/routers/words.py`
- [Vocabulary Page](https://github.com/yutomi141/paper_lens/blob/main/frontend/pages/words.tsx): `frontend/pages/words.tsx`

### Application Core

- [Settings Page](https://github.com/yutomi141/paper_lens/blob/main/frontend/pages/settings.tsx): `frontend/pages/settings.tsx`
- [FastAPI App](https://github.com/yutomi141/paper_lens/blob/main/backend/main.py): `backend/main.py`
- [SQLite Database](https://github.com/yutomi141/paper_lens/blob/main/backend/db/database.py): `backend/db/database.py`
- [Domain Models](https://github.com/yutomi141/paper_lens/blob/main/backend/db/models.py): `backend/db/models.py`

### Other components

- **Reader**

## Connections

- Reader → Paper Reader: opens (evidence: `README.md`)
- Reader → Paper Routes: uploads PDF (evidence: `README.md`)
- AI Side Panel → AI Routes: streams requests (evidence: `frontend/components/SidePanel.tsx`)
- AI Side Panel → Translation View: renders (evidence: `frontend/components/SidePanel.tsx`)
- AI Side Panel → References Panel: renders (evidence: `frontend/components/SidePanel.tsx`)
- AI Side Panel → Notes Panel: renders (evidence: `frontend/components/SidePanel.tsx`)
- AI Side Panel → Q&A Chat: renders (evidence: `frontend/components/SidePanel.tsx`)
- AI Routes → Prompt Builder: builds prompts (evidence: `backend/routers/ai.py`)
- AI Routes → Local Ollama: requests generation (evidence: `backend/routers/ai.py`)
- Paper Routes → PDF Extraction: extracts PDF text (evidence: `backend/routers/papers.py`)
- Paper Routes → Local Ollama: generates summary (evidence: `backend/routers/papers.py`)
- Paper Routes → Full-Text Translation: starts jobs (evidence: `backend/routers/papers.py`)
- FastAPI App → Paper Routes: registers (evidence: `backend/main.py`)
- FastAPI App → AI Routes: registers (evidence: `backend/main.py`)
- FastAPI App → Notes Routes: registers (evidence: `backend/main.py`)
- FastAPI App → Chat Routes: registers (evidence: `backend/main.py`)
- FastAPI App → Reference Routes: registers (evidence: `backend/main.py`)
- FastAPI App → Vocabulary Routes: registers (evidence: `backend/main.py`)
- Paper Routes → SQLite Database: reads and writes (evidence: `backend/routers/papers.py`)
- AI Routes → SQLite Database: reads and writes (evidence: `backend/routers/ai.py`)
- Notes Routes → SQLite Database: reads and writes (evidence: `backend/routers/notes.py`)
- Chat Routes → SQLite Database: reads and writes (evidence: `backend/routers/chat.py`)
- Reference Routes → SQLite Database: reads and writes (evidence: `backend/routers/references.py`)
- Vocabulary Routes → SQLite Database: reads and writes (evidence: `backend/routers/words.py`)
- Full-Text Translation → SQLite Database: tracks chunks (evidence: `backend/services/translation_job.py`)
- Full-Text Translation → PDF Extraction: extracts pages (evidence: `backend/services/translation_job.py`)
- Full-Text Translation → Local Ollama: translates chunks (evidence: `backend/services/translation_job.py`)
- Vocabulary Routes → Local Ollama: generates meanings (evidence: `backend/routers/words.py`)
- Domain Models → SQLite Database: uses base (evidence: `backend/db/models.py`)
