# mintpansy/scholardot architecture

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

- Interactive diagram: https://gitdiagram.com/mintpansy/scholardot
- Repository: https://github.com/mintpansy/scholardot

## Overview

ScholarDot is a web app for turning academic PDFs into sentence-level translations and a parallel-reading experience. The documented workflow runs from upload and document creation through asynchronous PDF parsing, translation, persistence, and progress polling, then into reading and study tools. The graph also preserves authentication, notes/highlights, reading-position state, summaries, complexity analysis, and figure/table assets. Some subsystem paths and links come from the README and tree; where sampled code did not establish a call, links are omitted or marked unverified.

Main entry points: [`backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java`](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java) (Translation pipeline), [`frontend/app/page.tsx`](https://github.com/mintpansy/scholardot/blob/main/frontend/app/page.tsx) (Next.js UI), [`backend/app/scholardot/src/main/java/swyp/scholardot/document/controller/DocumentPipelineController.java`](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/controller/DocumentPipelineController.java) (Document endpoints), [`frontend/app/components/read/Read.tsx`](https://github.com/mintpansy/scholardot/blob/main/frontend/app/components/read/Read.tsx) (Parallel reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["Next.js UI<br/>[page.tsx]"]
  node_document_api["Document API client<br/>[document.ts]"]
end

subgraph group_docs["Document processing"]
  node_backend["Spring API"]
  node_doc_controller["Document endpoints"]
  node_document[("Document records<br/>[Document.java]")]
  node_storage["PDF storage"]
  node_pipeline["Translation pipeline"]
  node_pdf_extract["PDF extraction"]
  node_units[("Sentence units")]
  node_unit_repo[("Unit repository")]
  node_translator["OpenAI translation"]
  node_assets[("Figure/table assets")]
  node_summary["Content summary"]
  node_analysis["Complexity analysis"]
  node_llm_chat["LLM chat service"]
end

subgraph group_study["Reading and study"]
  node_read_ui["Parallel reader<br/>[Read.tsx]"]
  node_notes[("Notes and highlights")]
  node_reading_state[("Reading position")]
end

subgraph group_identity["Identity and accounts"]
  node_auth["OAuth and JWT"]
end

node_reader(("Reader"))
node_openai["OpenAI API"]
node_kakao["Kakao OAuth"]

node_reader -->|"uses"| node_frontend
node_frontend -->|"requests"| node_document_api
node_document_api -->|"calls API"| node_backend
node_backend -.->|"routes"| node_doc_controller
node_doc_controller -->|"starts processing"| node_pipeline
node_doc_controller -->|"deletes"| node_document
node_pipeline -->|"extracts text"| node_pdf_extract
node_pipeline -->|"requests translation"| node_translator
node_translator -->|"translates via"| node_openai
node_pipeline -->|"creates units"| node_units
node_pipeline -->|"saves batches"| node_unit_repo
node_pipeline -->|"extracts assets"| node_assets
node_pipeline -.->|"generates summary"| node_summary
node_doc_controller -->|"serves analysis"| node_analysis
node_frontend -.->|"opens reader"| node_read_ui
node_read_ui -.->|"loads document"| node_document_api
node_read_ui -.->|"manages annotations"| node_notes
node_read_ui -.->|"restores position"| node_reading_state
node_kakao -->|"authenticates"| node_auth
node_llm_chat -->|"posts prompt"| node_openai
node_pipeline -->|"parses PDF"| node_pdf_extract
node_frontend -.->|"signs in"| node_auth

click node_frontend "https://github.com/mintpansy/scholardot/blob/main/frontend/app/page.tsx"
click node_document_api "https://github.com/mintpansy/scholardot/blob/main/frontend/app/services/document.ts"
click node_backend "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/ScholardotApplication.java"
click node_doc_controller "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/controller/DocumentPipelineController.java"
click node_document "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/domain/Document.java"
click node_storage "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/storage/ObjectStorageClient.java"
click node_pipeline "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java"
click node_pdf_extract "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/PdfTextExtractService.java"
click node_units "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/doc_units/docUnits/docUnitsEntity.java"
click node_unit_repo "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/doc_units/docUnits/docUnitsRepository.java"
click node_translator "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/translator/OpenAiTranslator.java"
click node_assets "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentAssetService.java"
click node_summary "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentContentSummaryService.java"
click node_analysis "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentStructureAnalysisService.java"
click node_read_ui "https://github.com/mintpansy/scholardot/blob/main/frontend/app/components/read/Read.tsx"
click node_notes "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/note/UserDocNoteService.java"
click node_reading_state "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/state/userDocStates/userDocStatesService.java"
click node_auth "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/domain/user/CustomOAuth2UserService.java"
click node_llm_chat "https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/api/callLLM/CallLLMService.java"

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_frontend,node_document_api toneBlue
class node_backend,node_doc_controller,node_document,node_storage,node_pipeline,node_pdf_extract,node_units,node_unit_repo,node_translator,node_assets,node_summary,node_analysis,node_llm_chat toneAmber
class node_read_ui,node_notes,node_reading_state,node_openai toneMint
class node_auth toneRose
class node_reader,node_kakao toneIndigo
```

## Components

### Web experience

- [Next.js UI](https://github.com/mintpansy/scholardot/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Document API client](https://github.com/mintpansy/scholardot/blob/main/frontend/app/services/document.ts): `frontend/app/services/document.ts`

### Document processing

- [Spring API](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/ScholardotApplication.java): `backend/app/scholardot/src/main/java/swyp/scholardot/ScholardotApplication.java`
- [Document endpoints](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/controller/DocumentPipelineController.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/controller/DocumentPipelineController.java`
- [Document records](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/domain/Document.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/domain/Document.java`
- [PDF storage](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/storage/ObjectStorageClient.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/storage/ObjectStorageClient.java`
- [Translation pipeline](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java`
- [PDF extraction](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/PdfTextExtractService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/PdfTextExtractService.java`
- [Sentence units](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/doc_units/docUnits/docUnitsEntity.java): `backend/app/scholardot/src/main/java/swyp/scholardot/doc_units/docUnits/docUnitsEntity.java`
- [Unit repository](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/doc_units/docUnits/docUnitsRepository.java): `backend/app/scholardot/src/main/java/swyp/scholardot/doc_units/docUnits/docUnitsRepository.java`
- [OpenAI translation](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/translator/OpenAiTranslator.java): `backend/app/scholardot/src/main/java/swyp/scholardot/translator/OpenAiTranslator.java`
- [Figure/table assets](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentAssetService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentAssetService.java`
- [Content summary](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentContentSummaryService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentContentSummaryService.java`
- [Complexity analysis](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentStructureAnalysisService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentStructureAnalysisService.java`
- [LLM chat service](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/api/callLLM/CallLLMService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/api/callLLM/CallLLMService.java`

### Reading and study

- [Parallel reader](https://github.com/mintpansy/scholardot/blob/main/frontend/app/components/read/Read.tsx): `frontend/app/components/read/Read.tsx`
- [Notes and highlights](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/document/note/UserDocNoteService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/document/note/UserDocNoteService.java`
- [Reading position](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/state/userDocStates/userDocStatesService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/state/userDocStates/userDocStatesService.java`

### Identity and accounts

- [OAuth and JWT](https://github.com/mintpansy/scholardot/blob/main/backend/app/scholardot/src/main/java/swyp/scholardot/domain/user/CustomOAuth2UserService.java): `backend/app/scholardot/src/main/java/swyp/scholardot/domain/user/CustomOAuth2UserService.java`

### Other components

- **Reader**
- **OpenAI API**
- **Kakao OAuth**

## Connections

- Reader → Next.js UI: uses (evidence: `README.md`)
- Next.js UI → Document API client: requests (evidence: `README.md`)
- Document API client → Spring API: calls API (evidence: `README.md`)
- Spring API → Document endpoints: routes
- Document endpoints → Translation pipeline: starts processing (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/document/controller/DocumentPipelineController.java`)
- Document endpoints → Document records: deletes (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/document/controller/DocumentPipelineController.java`)
- Translation pipeline → PDF extraction: extracts text (evidence: `README.md`)
- Translation pipeline → OpenAI translation: requests translation (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java`)
- OpenAI translation → OpenAI API: translates via (evidence: `README.md`)
- Translation pipeline → Sentence units: creates units (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java`)
- Translation pipeline → Unit repository: saves batches (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java`)
- Translation pipeline → Figure/table assets: extracts assets (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java`)
- Translation pipeline → Content summary: generates summary (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/document/service/DocumentPipelineService.java`)
- Document endpoints → Complexity analysis: serves analysis (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/document/controller/DocumentPipelineController.java`)
- Next.js UI → Parallel reader: opens reader
- Parallel reader → Document API client: loads document
- Parallel reader → Notes and highlights: manages annotations
- Parallel reader → Reading position: restores position
- Kakao OAuth → OAuth and JWT: authenticates (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/domain/user/CustomOAuth2UserService.java`)
- LLM chat service → OpenAI API: posts prompt (evidence: `backend/app/scholardot/src/main/java/swyp/scholardot/api/callLLM/CallLLMService.java`)
- Translation pipeline → PDF extraction: parses PDF (evidence: `README.md`)
- Next.js UI → OAuth and JWT: signs in