# saahilpal/rag-docanalyzer architecture

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

- Interactive diagram: https://gitdiagram.com/saahilpal/rag-docanalyzer
- Repository: https://github.com/saahilpal/rag-docanalyzer

## Overview

Document Analyzer is a chat-first PDF question-answering workspace. A user signs in, creates a conversation, uploads a PDF, waits for indexing, then asks questions and receives SSE-delivered answers grounded in retrieved document text. The API coordinates authentication, chat state, document attachment, quota checks, and generation; a database-polling worker parses and indexes files. The README documents frontend features and integrations beyond the sampled UI code; those relationships are shown as documented rather than implying unsampled implementation details.

Main entry points: [`src/controllers/chatController.js`](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/controllers/chatController.js) (Chat orchestration), [`src/database/client.js`](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/database/client.js) (PostgreSQL and pgvector), [`src/services/geminiService.js`](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/geminiService.js) (Gemini integration), [`frontend/src/lib/api.ts`](https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web workspace"]
  node_web["Next.js workspace<br/>[page.tsx]"]
  node_auth_ui["Sign-in UI<br/>[page.tsx]"]
  node_auth_hook["Auth state<br/>[use-auth.tsx]"]
  node_workspace_hook["Chat workspace state"]
  node_api_client["API client<br/>[api.ts]"]
  node_firebase_client["Firebase client<br/>[firebase.ts]"]
end

subgraph group_api["API and identity"]
  node_api_app["Express API<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_auth_controller["Auth exchange<br/>[authController.js]"]
  node_auth_service["User and session service<br/>[authService.js]"]
  node_chat_routes["Chat routes<br/>[chatRoutes.js]"]
  node_chat_controller["Chat orchestration<br/>[chatController.js]"]
end

subgraph group_documents["Document indexing"]
  node_document_service["Document attachment<br/>[documentService.js]"]
  node_worker["Indexing worker"]
  node_storage_service["File storage access<br/>[storageService.js]"]
end

subgraph group_answers["Grounded answers"]
  node_rag["Retrieval and prompts<br/>[ragService.js]"]
  node_gemini_service["Gemini integration<br/>[geminiService.js]"]
end

subgraph group_platform["Persistence and limits"]
  node_chat_service["Conversation persistence<br/>[chatService.js]"]
  node_database[("PostgreSQL and pgvector<br/>[client.js]")]
  node_quota["Chat quotas<br/>[quotaService.js]"]
end

node_user(("User"))
node_firebase["Firebase Auth"]
node_storage["Supabase Storage"]
node_gemini["Google Gemini"]

node_user -->|"signs in"| node_auth_ui
node_auth_ui -.->|"uses auth"| node_auth_hook
node_auth_hook -.->|"uses client"| node_firebase_client
node_firebase_client -->|"authenticates with"| node_firebase
node_auth_ui -->|"exchanges token"| node_api_client
node_web -.->|"uses workspace"| node_workspace_hook
node_workspace_hook -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"mounts routes"| node_auth_routes
node_api_app -->|"mounts routes"| node_chat_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"verifies token"| node_firebase
node_auth_controller -->|"upserts user"| node_auth_service
node_auth_service -->|"persists user"| node_database
node_chat_routes -->|"dispatches"| node_chat_controller
node_chat_controller -->|"manages chats"| node_chat_service
node_chat_controller -->|"manages attachments"| node_document_service
node_document_service -->|"uploads file"| node_storage_service
node_storage_service -->|"stores PDF"| node_storage
node_document_service -->|"records attachment"| node_database
node_worker -->|"claims and indexes"| node_database
node_worker -->|"downloads PDF"| node_storage_service
node_worker -->|"creates embeddings"| node_gemini_service
node_gemini_service -->|"requests embeddings"| node_gemini
node_chat_controller -->|"checks and consumes"| node_quota
node_chat_controller -->|"generates reply"| node_rag
node_rag -->|"retrieves chunks"| node_database
node_rag -->|"embeds and generates"| node_gemini_service
node_gemini_service -->|"generates answer"| node_gemini
node_chat_controller -->|"delivers SSE"| node_api_client
node_chat_controller -->|"saves messages"| node_chat_service
node_chat_service -->|"persists conversations"| node_database

click node_web "https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/app/app/page.tsx"
click node_auth_ui "https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/app/login/page.tsx"
click node_auth_hook "https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/hooks/use-auth.tsx"
click node_workspace_hook "https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/hooks/use-chat-workspace.tsx"
click node_api_client "https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/lib/api.ts"
click node_firebase_client "https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/lib/firebase.ts"
click node_api_app "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/app.js"
click node_auth_routes "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/routes/authRoutes.js"
click node_auth_controller "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/controllers/authController.js"
click node_auth_service "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/authService.js"
click node_chat_routes "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/routes/chatRoutes.js"
click node_chat_controller "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/controllers/chatController.js"
click node_document_service "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/documentService.js"
click node_worker "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/documentWorkerService.js"
click node_storage_service "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/storageService.js"
click node_chat_service "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/chatService.js"
click node_database "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/database/client.js"
click node_quota "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/quotaService.js"
click node_rag "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/ragService.js"
click node_gemini_service "https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/geminiService.js"

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,node_auth_ui,node_auth_hook,node_workspace_hook,node_api_client,node_firebase_client,node_user toneBlue
class node_api_app,node_auth_routes,node_auth_controller,node_auth_service,node_chat_routes,node_chat_controller,node_storage toneAmber
class node_document_service,node_worker,node_storage_service toneMint
class node_rag,node_gemini_service toneRose
class node_chat_service,node_database,node_quota,node_firebase,node_gemini toneIndigo
```

## Components

### Web workspace

- [Next.js workspace](https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/app/app/page.tsx): `frontend/src/app/app/page.tsx`
- [Sign-in UI](https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Auth state](https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/hooks/use-auth.tsx): `frontend/src/hooks/use-auth.tsx`
- [Chat workspace state](https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/hooks/use-chat-workspace.tsx): `frontend/src/hooks/use-chat-workspace.tsx`
- [API client](https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Firebase client](https://github.com/saahilpal/rag-docanalyzer/blob/master/frontend/src/lib/firebase.ts): `frontend/src/lib/firebase.ts`

### API and identity

- [Express API](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/app.js): `src/app.js`
- [Auth routes](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/routes/authRoutes.js): `src/routes/authRoutes.js`
- [Auth exchange](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/controllers/authController.js): `src/controllers/authController.js`
- [User and session service](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/authService.js): `src/services/authService.js`
- [Chat routes](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/routes/chatRoutes.js): `src/routes/chatRoutes.js`
- [Chat orchestration](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/controllers/chatController.js): `src/controllers/chatController.js`

### Document indexing

- [Document attachment](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/documentService.js): `src/services/documentService.js`
- [Indexing worker](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/documentWorkerService.js): `src/services/documentWorkerService.js`
- [File storage access](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/storageService.js): `src/services/storageService.js`

### Grounded answers

- [Retrieval and prompts](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/ragService.js): `src/services/ragService.js`
- [Gemini integration](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/geminiService.js): `src/services/geminiService.js`

### Persistence and limits

- [Conversation persistence](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/chatService.js): `src/services/chatService.js`
- [PostgreSQL and pgvector](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/database/client.js): `src/database/client.js`
- [Chat quotas](https://github.com/saahilpal/rag-docanalyzer/blob/master/src/services/quotaService.js): `src/services/quotaService.js`

### Other components

- **User**
- **Firebase Auth**
- **Supabase Storage**
- **Google Gemini**

## Connections

- User → Sign-in UI: signs in
- Sign-in UI → Auth state: uses auth
- Auth state → Firebase client: uses client
- Firebase client → Firebase Auth: authenticates with
- Sign-in UI → API client: exchanges token
- Next.js workspace → Chat workspace state: uses workspace
- Chat workspace state → API client: requests data
- API client → Express API: calls API
- Express API → Auth routes: mounts routes (evidence: `src/app.js`)
- Express API → Chat routes: mounts routes (evidence: `src/app.js`)
- Auth routes → Auth exchange: dispatches (evidence: `src/routes/authRoutes.js`)
- Auth exchange → Firebase Auth: verifies token (evidence: `src/controllers/authController.js`)
- Auth exchange → User and session service: upserts user (evidence: `src/controllers/authController.js`)
- User and session service → PostgreSQL and pgvector: persists user (evidence: `src/services/authService.js`)
- Chat routes → Chat orchestration: dispatches (evidence: `src/routes/chatRoutes.js`)
- Chat orchestration → Conversation persistence: manages chats (evidence: `src/controllers/chatController.js`)
- Chat orchestration → Document attachment: manages attachments (evidence: `src/controllers/chatController.js`)
- Document attachment → File storage access: uploads file (evidence: `src/services/documentService.js`)
- File storage access → Supabase Storage: stores PDF (evidence: `src/services/storageService.js`)
- Document attachment → PostgreSQL and pgvector: records attachment (evidence: `src/services/documentService.js`)
- Indexing worker → PostgreSQL and pgvector: claims and indexes (evidence: `src/services/documentWorkerService.js`)
- Indexing worker → File storage access: downloads PDF (evidence: `src/services/documentWorkerService.js`)
- Indexing worker → Gemini integration: creates embeddings (evidence: `src/services/documentWorkerService.js`)
- Gemini integration → Google Gemini: requests embeddings
- Chat orchestration → Chat quotas: checks and consumes (evidence: `src/controllers/chatController.js`)
- Chat orchestration → Retrieval and prompts: generates reply (evidence: `src/controllers/chatController.js`)
- Retrieval and prompts → PostgreSQL and pgvector: retrieves chunks (evidence: `src/services/ragService.js`)
- Retrieval and prompts → Gemini integration: embeds and generates (evidence: `src/services/ragService.js`)
- Gemini integration → Google Gemini: generates answer
- Chat orchestration → API client: delivers SSE
- Chat orchestration → Conversation persistence: saves messages (evidence: `src/controllers/chatController.js`)
- Conversation persistence → PostgreSQL and pgvector: persists conversations (evidence: `src/services/chatService.js`)
