# tthanh1223/papersanta_ttnn architecture

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

- Interactive diagram: https://gitdiagram.com/tthanh1223/papersanta_ttnn
- Repository: https://github.com/tthanh1223/papersanta_ttnn

## Overview

PaperSanta is a research-paper assistant: users authenticate, manage PDFs, read and analyze them, ask PDF-grounded questions, and discover related research. The main document flow is upload and storage, PDF extraction, chunking/embedding, then retrieval and generated answers; paper search and analysis are separate capabilities. The README and sampled routes/services support these connections; some service internals were not sampled, so their finer wiring is left unspecified.

Main entry points: [`frontend/src/App.tsx`](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/App.tsx) (Workspace UI), [`app/core/database.py`](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/core/database.py) (PostgreSQL with vectors), [`app/services/pdf_service.py`](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/pdf_service.py) (PDF operations), [`app/services/rag_service.py`](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/rag_service.py) (Retrieval and chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Research workspace"]
  node_web_app["Workspace UI<br/>[App.tsx]"]
  node_auth_ui["Auth context<br/>[AuthContext.tsx]"]
  node_pdf_client["PDF API client<br/>[pdf.ts]"]
  node_reader["PDF reader<br/>[Reader.tsx]"]
  node_analyzer_ui["Analyzer<br/>[Analyzer.tsx]"]
  node_discovery_ui["Discovery<br/>[Discovery.tsx]"]
  node_rag_client["RAG API client<br/>[rag.ts]"]
  node_search_client["Search API client<br/>[search.ts]"]
end

subgraph group_documents["PDF library and indexing"]
  node_pdf_routes["PDF endpoints<br/>[pdf_router.py]"]
  node_pdf_service["PDF operations<br/>[pdf_service.py]"]
  node_extraction["PDF extraction"]
  node_normalization["Text normalization"]
  node_chunk_embedding["Chunking and embeddings"]
end

subgraph group_research["AI and discovery"]
  node_rag_routes["RAG endpoints<br/>[rag_router.py]"]
  node_rag_service["Retrieval and chat<br/>[rag_service.py]"]
  node_embedding_provider["Embedding provider"]
  node_analysis_routes["Analysis endpoints<br/>[analyze_router.py]"]
  node_analysis_service["Document analysis<br/>[analyze_service.py]"]
  node_search_routes["Search endpoints<br/>[search_router.py]"]
  node_search_service["Paper search"]
end

subgraph group_platform["Identity and persistence"]
  node_document_records["PDF and chunk records<br/>[pdf_document.py]"]
  node_vector_records["Embedding records<br/>[embedding.py]"]
  node_chat_records["Chat sessions<br/>[chat.py]"]
  node_auth_service["JWT verification<br/>[auth.py]"]
  node_database[("PostgreSQL with vectors<br/>[database.py]")]
end

node_researcher(("Researcher"))
node_supabase_auth["Supabase Auth"]
node_supabase_storage[("Supabase Storage")]
node_deepseek["DeepSeek"]
node_sentence_transformers["Sentence Transformers"]
node_semantic_scholar["Semantic Scholar"]
node_gemini["Gemini"]
node_tavily["Tavily"]

node_researcher -->|"uses"| node_web_app
node_web_app -->|"authenticates via"| node_auth_ui
node_auth_ui -->|"signs in"| node_supabase_auth
node_web_app -->|"requests PDFs"| node_pdf_client
node_pdf_client -->|"calls"| node_pdf_routes
node_pdf_routes -->|"verifies user"| node_auth_service
node_pdf_routes -->|"delegates"| node_pdf_service
node_pdf_service -->|"extracts text"| node_extraction
node_extraction -->|"normalizes text"| node_normalization
node_pdf_service -->|"indexes document"| node_chunk_embedding
node_chunk_embedding -->|"creates vectors"| node_embedding_provider
node_chunk_embedding -->|"stores chunks and vectors"| node_database
node_pdf_service -->|"reads and writes"| node_database
node_pdf_service -->|"stores PDF files"| node_supabase_storage
node_web_app -->|"opens document"| node_reader
node_web_app -->|"opens analysis"| node_analyzer_ui
node_web_app -->|"opens discovery"| node_discovery_ui
node_rag_client -->|"calls"| node_rag_routes
node_researcher -->|"asks PDF questions"| node_rag_client
node_rag_routes -->|"verifies user"| node_auth_service
node_rag_routes -->|"delegates chat"| node_rag_service
node_rag_service -->|"embeds query"| node_embedding_provider
node_rag_service -->|"retrieves and saves"| node_database
node_rag_service -->|"generates answer"| node_deepseek
node_rag_service -->|"persists session"| node_chat_records
node_embedding_provider -->|"embeds text"| node_sentence_transformers
node_analyzer_ui -->|"requests analysis"| node_analysis_routes
node_analysis_routes -->|"delegates"| node_analysis_service
node_analysis_service -->|"analyzes content"| node_deepseek
node_search_client -->|"calls"| node_search_routes
node_discovery_ui -->|"finds related papers"| node_search_client
node_search_routes -->|"delegates"| node_search_service
node_search_service -->|"reads paper topics"| node_database
node_search_service -.->|"searches papers"| node_semantic_scholar
node_search_service -.->|"formats results"| node_gemini
node_search_service -.->|"searches papers"| node_tavily
node_document_records -->|"persisted in"| node_database
node_vector_records -->|"persisted in"| node_database
node_chat_records -->|"persisted in"| node_database

click node_web_app "https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/context/AuthContext.tsx"
click node_pdf_client "https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/api/pdf.ts"
click node_reader "https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/components/Reader.tsx"
click node_analyzer_ui "https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/components/Analyzer.tsx"
click node_discovery_ui "https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/components/Discovery.tsx"
click node_rag_client "https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/api/rag.ts"
click node_search_client "https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/api/search.ts"
click node_pdf_routes "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/api/pdf_router.py"
click node_pdf_service "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/pdf_service.py"
click node_extraction "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/extraction_service.py"
click node_normalization "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/text_normalization_service.py"
click node_chunk_embedding "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/embedding_service.py"
click node_document_records "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/models/pdf_document.py"
click node_vector_records "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/models/embedding.py"
click node_chat_records "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/models/chat.py"
click node_rag_routes "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/api/rag_router.py"
click node_rag_service "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/rag_service.py"
click node_embedding_provider "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/core/embedding_provider.py"
click node_analysis_routes "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/api/analyze_router.py"
click node_analysis_service "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/analyze_service.py"
click node_search_routes "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/api/search_router.py"
click node_search_service "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/paper_search_service.py"
click node_auth_service "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/core/auth.py"
click node_database "https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/core/database.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_web_app,node_auth_ui,node_pdf_client,node_reader,node_analyzer_ui,node_discovery_ui,node_rag_client,node_search_client toneBlue
class node_pdf_routes,node_pdf_service,node_extraction,node_normalization,node_chunk_embedding,node_supabase_storage toneAmber
class node_rag_routes,node_rag_service,node_embedding_provider,node_analysis_routes,node_analysis_service,node_search_routes,node_search_service toneMint
class node_document_records,node_vector_records,node_chat_records,node_auth_service,node_database toneRose
class node_researcher,node_supabase_auth,node_deepseek,node_sentence_transformers,node_semantic_scholar,node_gemini,node_tavily toneIndigo
```

## Components

### Research workspace

- [Workspace UI](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [PDF API client](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/api/pdf.ts): `frontend/src/api/pdf.ts`
- [PDF reader](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/components/Reader.tsx): `frontend/src/components/Reader.tsx`
- [Analyzer](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/components/Analyzer.tsx): `frontend/src/components/Analyzer.tsx`
- [Discovery](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/components/Discovery.tsx): `frontend/src/components/Discovery.tsx`
- [RAG API client](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/api/rag.ts): `frontend/src/api/rag.ts`
- [Search API client](https://github.com/tthanh1223/papersanta_ttnn/blob/main/frontend/src/api/search.ts): `frontend/src/api/search.ts`

### PDF library and indexing

- [PDF endpoints](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/api/pdf_router.py): `app/api/pdf_router.py`
- [PDF operations](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/pdf_service.py): `app/services/pdf_service.py`
- [PDF extraction](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/extraction_service.py): `app/services/extraction_service.py`
- [Text normalization](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/text_normalization_service.py): `app/services/text_normalization_service.py`
- [Chunking and embeddings](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/embedding_service.py): `app/services/embedding_service.py`

### AI and discovery

- [RAG endpoints](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/api/rag_router.py): `app/api/rag_router.py`
- [Retrieval and chat](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/rag_service.py): `app/services/rag_service.py`
- [Embedding provider](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/core/embedding_provider.py): `app/core/embedding_provider.py`
- [Analysis endpoints](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/api/analyze_router.py): `app/api/analyze_router.py`
- [Document analysis](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/analyze_service.py): `app/services/analyze_service.py`
- [Search endpoints](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/api/search_router.py): `app/api/search_router.py`
- [Paper search](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/services/paper_search_service.py): `app/services/paper_search_service.py`

### Identity and persistence

- [PDF and chunk records](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/models/pdf_document.py): `app/models/pdf_document.py`
- [Embedding records](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/models/embedding.py): `app/models/embedding.py`
- [Chat sessions](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/models/chat.py): `app/models/chat.py`
- [JWT verification](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/core/auth.py): `app/core/auth.py`
- [PostgreSQL with vectors](https://github.com/tthanh1223/papersanta_ttnn/blob/main/app/core/database.py): `app/core/database.py`

### Other components

- **Researcher**
- **Supabase Auth**
- **Supabase Storage**
- **DeepSeek**
- **Sentence Transformers**
- **Semantic Scholar**
- **Gemini**
- **Tavily**

## Connections

- Researcher → Workspace UI: uses
- Workspace UI → Auth context: authenticates via
- Auth context → Supabase Auth: signs in
- Workspace UI → PDF API client: requests PDFs
- PDF API client → PDF endpoints: calls
- PDF endpoints → JWT verification: verifies user
- PDF endpoints → PDF operations: delegates
- PDF operations → PDF extraction: extracts text
- PDF extraction → Text normalization: normalizes text
- PDF operations → Chunking and embeddings: indexes document
- Chunking and embeddings → Embedding provider: creates vectors
- Chunking and embeddings → PostgreSQL with vectors: stores chunks and vectors
- PDF operations → PostgreSQL with vectors: reads and writes
- PDF operations → Supabase Storage: stores PDF files
- Workspace UI → PDF reader: opens document
- Workspace UI → Analyzer: opens analysis
- Workspace UI → Discovery: opens discovery
- RAG API client → RAG endpoints: calls
- Researcher → RAG API client: asks PDF questions
- RAG endpoints → JWT verification: verifies user
- RAG endpoints → Retrieval and chat: delegates chat
- Retrieval and chat → Embedding provider: embeds query
- Retrieval and chat → PostgreSQL with vectors: retrieves and saves
- Retrieval and chat → DeepSeek: generates answer
- Retrieval and chat → Chat sessions: persists session
- Embedding provider → Sentence Transformers: embeds text
- Analyzer → Analysis endpoints: requests analysis
- Analysis endpoints → Document analysis: delegates
- Document analysis → DeepSeek: analyzes content
- Search API client → Search endpoints: calls
- Discovery → Search API client: finds related papers
- Search endpoints → Paper search: delegates
- Paper search → PostgreSQL with vectors: reads paper topics
- Paper search → Semantic Scholar: searches papers
- Paper search → Gemini: formats results
- Paper search → Tavily: searches papers
- PDF and chunk records → PostgreSQL with vectors: persisted in
- Embedding records → PostgreSQL with vectors: persisted in
- Chat sessions → PostgreSQL with vectors: persisted in