# vars-123/rag-document-qa architecture

> Architecture diagram of the GitHub repository vars-123/rag-document-qa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vars-123/rag-document-qa
- Repository: https://github.com/vars-123/rag-document-qa

## Overview

RAG PDF question answering: users upload PDFs, track ingestion until documents are embedded, then select a document and ask questions; answers stream back with conversation history and session management. The frontend coordinates document and chat workflows, while FastAPI routes delegate to ingestion, retrieval, and history services. SQLite stores chat history and ChromaDB stores embeddings. The README also documents per-user isolation and deployment readiness. Edges reflect shown calls, imports, or HTTP routes; unsampled implementation details are omitted.

Main entry points: [`backend/app/routers/documents.py`](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/routers/documents.py) (Document routes), [`frontend/src/App.tsx`](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/App.tsx) (Workspace), [`frontend/src/services/api.ts`](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/services/api.ts) (HTTP client), [`backend/app/main.py`](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/main.py) (API startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["Workspace<br/>[App.tsx]"]
  node_upload["PDF upload UI<br/>[UploadZone.tsx]"]
  node_doclist["Document list<br/>[DocumentList.tsx]"]
  node_docshook["Document workflow<br/>[useDocuments.ts]"]
  node_chatui["Chat interface<br/>[ChatInterface.tsx]"]
  node_chathook["Chat sessions<br/>[useChat.ts]"]
  node_convhook["Conversation list"]
  node_api_client["HTTP client<br/>[api.ts]"]
end

subgraph group_api["API routes"]
  node_main["API startup<br/>[main.py]"]
  node_documents["Document routes<br/>[documents.py]"]
  node_chat["Chat routes<br/>[chat.py]"]
  node_health["Health route<br/>[health.py]"]
end

subgraph group_rag["Document and RAG"]
  node_pdf["PDF extraction<br/>[pdf_service.py]"]
  node_chunking["Text chunking"]
  node_embedding["Embedding service"]
  node_chatservice["Retrieval and generation<br/>[chat_service.py]"]
end

subgraph group_state["Persistent state"]
  node_vector[("Vector search<br/>[vector_service.py]")]
  node_history[("Conversation history")]
end

node_user(("User"))
node_gemini{{"Google Gemini"}}
node_sqlite[("SQLite")]
node_chroma[("ChromaDB")]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_upload
node_app -->|"renders"| node_doclist
node_app -->|"uses"| node_docshook
node_app -->|"renders"| node_chatui
node_docshook -->|"requests"| node_api_client
node_chatui -->|"uses"| node_chathook
node_chatui -->|"uses"| node_convhook
node_chathook -->|"requests"| node_api_client
node_convhook -->|"requests"| node_api_client
node_api_client -->|"HTTP requests"| node_documents
node_api_client -->|"HTTP requests"| node_chat
node_app -->|"checks"| node_health
node_main -->|"registers"| node_documents
node_main -->|"registers"| node_chat
node_main -->|"registers"| node_health
node_main -->|"initializes"| node_history
node_documents -->|"extracts text"| node_pdf
node_documents -->|"chunks text"| node_chunking
node_documents -->|"embeds chunks"| node_embedding
node_documents -->|"deletes collection"| node_vector
node_documents -->|"deletes history"| node_history
node_chat -->|"delegates"| node_chatservice
node_chat -->|"reads and writes"| node_history
node_chatservice -->|"embeds query"| node_embedding
node_chatservice -->|"searches"| node_vector
node_embedding -->|"stores vectors"| node_vector
node_embedding -->|"generates embeddings"| node_gemini
node_chatservice -->|"streams completion"| node_gemini
node_vector -->|"reads and writes"| node_chroma
node_history -->|"reads and writes"| node_sqlite

click node_app "https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/App.tsx"
click node_upload "https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/components/UploadZone.tsx"
click node_doclist "https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/components/DocumentList.tsx"
click node_docshook "https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/hooks/useDocuments.ts"
click node_chatui "https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/components/ChatInterface.tsx"
click node_chathook "https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/hooks/useChat.ts"
click node_convhook "https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/hooks/useConversations.ts"
click node_api_client "https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/services/api.ts"
click node_main "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/main.py"
click node_documents "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/routers/documents.py"
click node_chat "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/routers/chat.py"
click node_health "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/routers/health.py"
click node_pdf "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/pdf_service.py"
click node_chunking "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/chunking_service.py"
click node_embedding "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/embedding_service.py"
click node_chatservice "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/chat_service.py"
click node_vector "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/vector_service.py"
click node_history "https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/chat_history_service.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_app,node_upload,node_doclist,node_docshook,node_chatui,node_chathook,node_convhook,node_api_client,node_user toneBlue
class node_main,node_documents,node_chat,node_health,node_sqlite,node_chroma toneAmber
class node_pdf,node_chunking,node_embedding,node_chatservice toneMint
class node_vector,node_history toneRose
class node_gemini toneIndigo
```

## Components

### Frontend experience

- [Workspace](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [PDF upload UI](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/components/UploadZone.tsx): `frontend/src/components/UploadZone.tsx`
- [Document list](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/components/DocumentList.tsx): `frontend/src/components/DocumentList.tsx`
- [Document workflow](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/hooks/useDocuments.ts): `frontend/src/hooks/useDocuments.ts`
- [Chat interface](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/components/ChatInterface.tsx): `frontend/src/components/ChatInterface.tsx`
- [Chat sessions](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/hooks/useChat.ts): `frontend/src/hooks/useChat.ts`
- [Conversation list](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/hooks/useConversations.ts): `frontend/src/hooks/useConversations.ts`
- [HTTP client](https://github.com/vars-123/rag-document-qa/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API routes

- [API startup](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/main.py): `backend/app/main.py`
- [Document routes](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/routers/documents.py): `backend/app/routers/documents.py`
- [Chat routes](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/routers/chat.py): `backend/app/routers/chat.py`
- [Health route](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/routers/health.py): `backend/app/routers/health.py`

### Document and RAG

- [PDF extraction](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`
- [Text chunking](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/chunking_service.py): `backend/app/services/chunking_service.py`
- [Embedding service](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`
- [Retrieval and generation](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`

### Persistent state

- [Vector search](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/vector_service.py): `backend/app/services/vector_service.py`
- [Conversation history](https://github.com/vars-123/rag-document-qa/blob/main/backend/app/services/chat_history_service.py): `backend/app/services/chat_history_service.py`

### Other components

- **User**
- **Google Gemini**
- **SQLite**
- **ChromaDB**

## Connections

- User → Workspace: uses (evidence: `frontend/src/App.tsx`)
- Workspace → PDF upload UI: renders (evidence: `frontend/src/App.tsx`)
- Workspace → Document list: renders (evidence: `frontend/src/App.tsx`)
- Workspace → Document workflow: uses (evidence: `frontend/src/App.tsx`)
- Workspace → Chat interface: renders (evidence: `frontend/src/App.tsx`)
- Document workflow → HTTP client: requests (evidence: `frontend/src/hooks/useDocuments.ts`)
- Chat interface → Chat sessions: uses (evidence: `frontend/src/components/ChatInterface.tsx`)
- Chat interface → Conversation list: uses (evidence: `frontend/src/components/ChatInterface.tsx`)
- Chat sessions → HTTP client: requests (evidence: `frontend/src/hooks/useChat.ts`)
- Conversation list → HTTP client: requests (evidence: `frontend/src/hooks/useConversations.ts`)
- HTTP client → Document routes: HTTP requests (evidence: `frontend/src/services/api.ts`)
- HTTP client → Chat routes: HTTP requests (evidence: `frontend/src/services/api.ts`)
- Workspace → Health route: checks (evidence: `frontend/src/App.tsx`)
- API startup → Document routes: registers (evidence: `backend/app/main.py`)
- API startup → Chat routes: registers (evidence: `backend/app/main.py`)
- API startup → Health route: registers (evidence: `backend/app/main.py`)
- API startup → Conversation history: initializes (evidence: `backend/app/main.py`)
- Document routes → PDF extraction: extracts text (evidence: `backend/app/routers/documents.py`)
- Document routes → Text chunking: chunks text (evidence: `backend/app/routers/documents.py`)
- Document routes → Embedding service: embeds chunks (evidence: `backend/app/routers/documents.py`)
- Document routes → Vector search: deletes collection (evidence: `backend/app/routers/documents.py`)
- Document routes → Conversation history: deletes history (evidence: `backend/app/routers/documents.py`)
- Chat routes → Retrieval and generation: delegates (evidence: `backend/app/routers/chat.py`)
- Chat routes → Conversation history: reads and writes (evidence: `backend/app/routers/chat.py`)
- Retrieval and generation → Embedding service: embeds query (evidence: `backend/app/services/chat_service.py`)
- Retrieval and generation → Vector search: searches (evidence: `backend/app/services/chat_service.py`)
- Embedding service → Vector search: stores vectors (evidence: `backend/app/services/embedding_service.py`)
- Embedding service → Google Gemini: generates embeddings (evidence: `backend/app/services/embedding_service.py`)
- Retrieval and generation → Google Gemini: streams completion (evidence: `backend/app/services/chat_service.py`)
- Vector search → ChromaDB: reads and writes (evidence: `backend/app/services/vector_service.py`)
- Conversation history → SQLite: reads and writes (evidence: `backend/app/services/chat_history_service.py`)
