# karlcyrus/paperbrain-rag-llm-pipeline architecture

> Architecture diagram of the GitHub repository karlcyrus/paperbrain-rag-llm-pipeline, 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/karlcyrus/paperbrain-rag-llm-pipeline
- Repository: https://github.com/karlcyrus/paperbrain-rag-llm-pipeline

## Overview

PaperBrain lets users upload PDFs, TXT, and DOCX files, then ask single- or multi-document questions and receive streaming answers with source citations. Uploads are parsed, chunked, embedded, and stored for vector search; chat embeds each question, retrieves matching passages, and sends a grounded prompt to Gemini. The README documents persistent chat history, document management, authentication, and theme support. Unsampled subsystems are included where documented; their internal wiring is not inferred.

Main entry points: [`src/app/chat/multi/page.tsx`](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/chat/multi/page.tsx) (Multi-Document Chat), [`src/app/chat/[documentId]/page.tsx`](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/chat/%5BdocumentId%5D/page.tsx) (Document Chat), [`src/app/api/upload/route.ts`](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/api/upload/route.ts) (Upload Endpoint), [`src/app/api/chat/route.ts`](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/api/chat/route.ts) (RAG Chat Endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product_ui["Product UI"]
  node_auth_pages["Sign-in and Signup<br/>[page.tsx]"]
  node_dashboard["Document Dashboard<br/>[page.tsx]"]
  node_upload_zone["Upload Zone<br/>[UploadZone.tsx]"]
  node_chat_single["Document Chat<br/>[page.tsx]"]
  node_chat_multi["Multi-Document Chat<br/>[page.tsx]"]
  node_chat_input["Chat Input<br/>[ChatInput.tsx]"]
  node_chat_display["Chat Messages<br/>[ChatMessage.tsx]"]
  node_citations["Source Citations<br/>[SourceCitation.tsx]"]
  node_navbar["Navigation and Logout<br/>[Navbar.tsx]"]
  node_theme["Theme Controls<br/>[ThemeProvider.tsx]"]
  node_document_card["Document Card<br/>[DocumentCard.tsx]"]
  node_empty_state["Empty State<br/>[EmptyState.tsx]"]
end

subgraph group_ingest["Document Ingestion"]
  node_upload_api["Upload Endpoint<br/>[route.ts]"]
  node_parser["File Parser<br/>[parser.ts]"]
  node_chunker["Text Chunker<br/>[chunker.ts]"]
end

subgraph group_rag["Retrieval and Answers"]
  node_embedding["Embedding API<br/>[gemini.ts]"]
  node_chat_api["RAG Chat Endpoint<br/>[route.ts]"]
  node_gemini["Gemini Generation<br/>[gemini.ts]"]
end

subgraph group_platform["Identity and Storage"]
  node_auth_callback["Auth Callback<br/>[route.ts]"]
  node_vector_store[("Document and Chunk Store")]
  node_document_api["Document List and Delete<br/>[route.ts]"]
  node_browser_supabase["Browser Supabase Client<br/>[supabase.ts]"]
  node_server_supabase["Server Supabase Client<br/>[supabase-server.ts]"]
  node_proxy["Auth Proxy<br/>[proxy.ts]"]
end

node_user(("User"))

node_user -->|"signs in"| node_auth_pages
node_auth_pages -->|"authenticates"| node_browser_supabase
node_auth_callback -.->|"completes auth"| node_server_supabase
node_user -->|"manages documents"| node_dashboard
node_dashboard -->|"renders"| node_upload_zone
node_upload_zone -->|"posts file"| node_upload_api
node_upload_api -->|"authenticates and stores"| node_server_supabase
node_upload_api -->|"parses file"| node_parser
node_upload_api -->|"chunks text"| node_chunker
node_upload_api -->|"embeds chunks"| node_embedding
node_upload_api -->|"writes document and chunks"| node_vector_store
node_user -->|"asks questions"| node_chat_single
node_user -->|"asks across documents"| node_chat_multi
node_chat_single -->|"renders"| node_chat_input
node_chat_multi -->|"renders"| node_chat_input
node_chat_input -->|"submits question"| node_chat_single
node_chat_input -->|"submits question"| node_chat_multi
node_chat_single -.->|"posts question"| node_chat_api
node_chat_multi -->|"posts question and IDs"| node_chat_api
node_chat_api -->|"authenticates and searches"| node_server_supabase
node_chat_api -->|"embeds question"| node_embedding
node_chat_api -->|"retrieves matching chunks"| node_vector_store
node_chat_api -->|"generates stream"| node_gemini
node_chat_single -->|"loads user session"| node_browser_supabase
node_chat_multi -->|"loads user session"| node_browser_supabase
node_chat_multi -->|"loads document names"| node_document_api
node_dashboard -->|"lists documents"| node_document_api
node_document_api -->|"reads and deletes records"| node_server_supabase
node_chat_single -->|"renders messages"| node_chat_display
node_chat_multi -->|"renders messages"| node_chat_display
node_chat_single -->|"renders sources"| node_citations
node_chat_multi -->|"renders sources"| node_citations
node_dashboard -->|"renders documents"| node_document_card
node_dashboard -->|"renders empty view"| node_empty_state
node_chat_multi -->|"renders empty view"| node_empty_state
node_navbar -->|"signs out"| node_browser_supabase
node_navbar -.->|"provides theme control"| node_theme
node_proxy -.->|"refreshes sessions"| node_server_supabase
node_user -->|"navigates and toggles theme"| node_navbar

click node_auth_pages "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/signup/page.tsx"
click node_auth_callback "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/auth/callback/route.ts"
click node_dashboard "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/dashboard/page.tsx"
click node_upload_zone "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/UploadZone.tsx"
click node_upload_api "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/api/upload/route.ts"
click node_parser "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/parser.ts"
click node_chunker "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/chunker.ts"
click node_embedding "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/gemini.ts"
click node_chat_single "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/chat/%5BdocumentId%5D/page.tsx"
click node_chat_multi "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/chat/multi/page.tsx"
click node_chat_input "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/ChatInput.tsx"
click node_chat_api "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/api/chat/route.ts"
click node_chat_display "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/ChatMessage.tsx"
click node_citations "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/SourceCitation.tsx"
click node_gemini "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/gemini.ts"
click node_document_api "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/api/documents/route.ts"
click node_browser_supabase "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/supabase.ts"
click node_server_supabase "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/supabase-server.ts"
click node_proxy "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/proxy.ts"
click node_navbar "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/Navbar.tsx"
click node_theme "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/ThemeProvider.tsx"
click node_document_card "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/DocumentCard.tsx"
click node_empty_state "https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/EmptyState.tsx"

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_auth_pages,node_dashboard,node_upload_zone,node_chat_single,node_chat_multi,node_chat_input,node_chat_display,node_citations,node_navbar,node_theme,node_document_card,node_empty_state,node_user toneBlue
class node_upload_api,node_parser,node_chunker toneAmber
class node_embedding,node_chat_api,node_gemini toneMint
class node_auth_callback,node_vector_store,node_document_api,node_browser_supabase,node_server_supabase,node_proxy toneRose
```

## Components

### Product UI

- [Sign-in and Signup](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/signup/page.tsx): `src/app/signup/page.tsx`
- [Document Dashboard](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Upload Zone](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/UploadZone.tsx): `src/components/UploadZone.tsx`
- [Document Chat](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/chat/%5BdocumentId%5D/page.tsx): `src/app/chat/[documentId]/page.tsx`
- [Multi-Document Chat](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/chat/multi/page.tsx): `src/app/chat/multi/page.tsx`
- [Chat Input](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/ChatInput.tsx): `src/components/ChatInput.tsx`
- [Chat Messages](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/ChatMessage.tsx): `src/components/ChatMessage.tsx`
- [Source Citations](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/SourceCitation.tsx): `src/components/SourceCitation.tsx`
- [Navigation and Logout](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/Navbar.tsx): `src/components/Navbar.tsx`
- [Theme Controls](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/ThemeProvider.tsx): `src/components/ThemeProvider.tsx`
- [Document Card](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/DocumentCard.tsx): `src/components/DocumentCard.tsx`
- [Empty State](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/components/EmptyState.tsx): `src/components/EmptyState.tsx`

### Document Ingestion

- [Upload Endpoint](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/api/upload/route.ts): `src/app/api/upload/route.ts`
- [File Parser](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/parser.ts): `src/lib/parser.ts`
- [Text Chunker](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/chunker.ts): `src/lib/chunker.ts`

### Retrieval and Answers

- [Embedding API](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/gemini.ts): `src/lib/gemini.ts`
- [RAG Chat Endpoint](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Gemini Generation](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/gemini.ts): `src/lib/gemini.ts`

### Identity and Storage

- [Auth Callback](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/auth/callback/route.ts): `src/app/auth/callback/route.ts`
- **Document and Chunk Store**
- [Document List and Delete](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/app/api/documents/route.ts): `src/app/api/documents/route.ts`
- [Browser Supabase Client](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`
- [Server Supabase Client](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/lib/supabase-server.ts): `src/lib/supabase-server.ts`
- [Auth Proxy](https://github.com/karlcyrus/paperbrain-rag-llm-pipeline/blob/main/src/proxy.ts): `src/proxy.ts`

### Other components

- **User**

## Connections

- User → Sign-in and Signup: signs in (evidence: `README.md`)
- Sign-in and Signup → Browser Supabase Client: authenticates (evidence: `src/app/signup/page.tsx`)
- Auth Callback → Server Supabase Client: completes auth
- User → Document Dashboard: manages documents (evidence: `README.md`)
- Document Dashboard → Upload Zone: renders (evidence: `src/app/dashboard/page.tsx`)
- Upload Zone → Upload Endpoint: posts file (evidence: `src/components/UploadZone.tsx`)
- Upload Endpoint → Server Supabase Client: authenticates and stores (evidence: `src/app/api/upload/route.ts`)
- Upload Endpoint → File Parser: parses file (evidence: `src/app/api/upload/route.ts`)
- Upload Endpoint → Text Chunker: chunks text (evidence: `src/app/api/upload/route.ts`)
- Upload Endpoint → Embedding API: embeds chunks (evidence: `src/app/api/upload/route.ts`)
- Upload Endpoint → Document and Chunk Store: writes document and chunks (evidence: `src/app/api/upload/route.ts`)
- User → Document Chat: asks questions (evidence: `README.md`)
- User → Multi-Document Chat: asks across documents (evidence: `README.md`)
- Document Chat → Chat Input: renders (evidence: `src/app/chat/[documentId]/page.tsx`)
- Multi-Document Chat → Chat Input: renders (evidence: `src/app/chat/multi/page.tsx`)
- Chat Input → Document Chat: submits question (evidence: `src/components/ChatInput.tsx`)
- Chat Input → Multi-Document Chat: submits question (evidence: `src/components/ChatInput.tsx`)
- Document Chat → RAG Chat Endpoint: posts question
- Multi-Document Chat → RAG Chat Endpoint: posts question and IDs (evidence: `src/app/chat/multi/page.tsx`)
- RAG Chat Endpoint → Server Supabase Client: authenticates and searches (evidence: `src/app/api/chat/route.ts`)
- RAG Chat Endpoint → Embedding API: embeds question (evidence: `src/app/api/chat/route.ts`)
- RAG Chat Endpoint → Document and Chunk Store: retrieves matching chunks (evidence: `README.md`)
- RAG Chat Endpoint → Gemini Generation: generates stream (evidence: `src/app/api/chat/route.ts`)
- Document Chat → Browser Supabase Client: loads user session (evidence: `src/app/chat/[documentId]/page.tsx`)
- Multi-Document Chat → Browser Supabase Client: loads user session (evidence: `src/app/chat/multi/page.tsx`)
- Multi-Document Chat → Document List and Delete: loads document names (evidence: `src/app/chat/multi/page.tsx`)
- Document Dashboard → Document List and Delete: lists documents (evidence: `src/app/dashboard/page.tsx`)
- Document List and Delete → Server Supabase Client: reads and deletes records (evidence: `src/app/api/documents/route.ts`)
- Document Chat → Chat Messages: renders messages (evidence: `src/app/chat/[documentId]/page.tsx`)
- Multi-Document Chat → Chat Messages: renders messages (evidence: `src/app/chat/multi/page.tsx`)
- Document Chat → Source Citations: renders sources (evidence: `src/app/chat/[documentId]/page.tsx`)
- Multi-Document Chat → Source Citations: renders sources (evidence: `src/app/chat/multi/page.tsx`)
- Document Dashboard → Document Card: renders documents (evidence: `src/app/dashboard/page.tsx`)
- Document Dashboard → Empty State: renders empty view (evidence: `src/app/dashboard/page.tsx`)
- Multi-Document Chat → Empty State: renders empty view (evidence: `src/app/chat/multi/page.tsx`)
- Navigation and Logout → Browser Supabase Client: signs out (evidence: `src/components/Navbar.tsx`)
- Navigation and Logout → Theme Controls: provides theme control
- Auth Proxy → Server Supabase Client: refreshes sessions
- User → Navigation and Logout: navigates and toggles theme (evidence: `README.md`)