# devanshu23bcs030/rag-eval-project architecture

> Architecture diagram of the GitHub repository devanshu23bcs030/rag-eval-project, 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/devanshu23bcs030/rag-eval-project
- Repository: https://github.com/devanshu23bcs030/rag-eval-project

## Overview

This is a PDF chat and retrieval-augmented generation platform with an evaluation harness. Users authenticate, upload a PDF with a retrieval strategy, then chat against its indexed contents and review cited source chunks; they can also manage documents and credits. Upload processing runs asynchronously, while question answering retrieves context, generates an answer, and records chat and evaluation telemetry. The graph preserves the documented fixed, semantic, and hybrid retrieval options. Several frontend/backend and external-service links are based on README architecture statements because the relevant implementation wiring was not excerpted.

Main entry points: [`backend/src/controllers/documentController.js`](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/controllers/documentController.js) (Document controller), [`frontend/src/App.jsx`](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/App.jsx) (App navigation), [`backend/src/server.js`](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/server.js) (Express API), [`backend/src/workers/pdfWorker.js`](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/workers/pdfWorker.js) (PDF worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["App navigation<br/>[App.jsx]"]
  node_authscreen["Sign-in screen<br/>[AuthScreen.jsx]"]
  node_uploadscreen["Upload screen<br/>[UploadScreen.jsx]"]
  node_documentscreen["Document list"]
  node_chatscreen["Chat screen<br/>[ChatScreen.jsx]"]
  node_paymentscreen["Credit screen<br/>[PaymentScreen.jsx]"]
end

subgraph group_api["API and identity"]
  node_server["Express API<br/>[server.js]"]
  node_auth["Auth controller<br/>[authController.js]"]
  node_authmw["JWT authentication<br/>[authMiddleware.js]"]
  node_doccontroller["Document controller"]
  node_routes["Delete route<br/>[documentRoutes.js]"]
  node_uploadmw["PDF upload middleware<br/>[upload.js]"]
end

subgraph group_retrieval["PDF and retrieval"]
  node_worker["PDF worker<br/>[pdfWorker.js]"]
  node_pdfparse["PDF parsing<br/>[pdfService.js]"]
  node_chunking["Chunking strategies<br/>[chunkingService.js]"]
  node_vectors["Vector and hybrid search<br/>[vectorStore.js]"]
  node_bm25["BM25 ranking<br/>[bm25Service.js]"]
  node_answer["Answer generation<br/>[llmService.js]"]
end

subgraph group_persistence["Data and telemetry"]
  node_mongo[("MongoDB")]
  node_models["Document, user, chat models"]
  node_sqlite[("SQLite telemetry<br/>[dbService.js]")]
end

subgraph group_evaluation["Retrieval evaluation"]
  node_evals["Strategy benchmark<br/>[runEvals.js]"]
end

node_user(("User"))
node_clerk["Clerk identity"]
node_cloudinary["Cloudinary files"]
node_redis["Redis job queue"]
node_chromadb[("ChromaDB index")]
node_gemini["Gemini model"]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_authscreen
node_app -->|"renders"| node_uploadscreen
node_app -->|"renders"| node_documentscreen
node_app -->|"renders"| node_chatscreen
node_app -->|"renders"| node_paymentscreen
node_authscreen -->|"authenticates"| node_clerk
node_app -->|"calls auth API"| node_server
node_server -->|"routes auth"| node_auth
node_server -->|"guards endpoints"| node_authmw
node_server -->|"routes document API"| node_doccontroller
node_server -->|"mounts delete route"| node_routes
node_routes -->|"guards delete"| node_authmw
node_routes -->|"dispatches delete"| node_doccontroller
node_server -->|"accepts PDF"| node_uploadmw
node_doccontroller -->|"reads and writes"| node_models
node_auth -->|"reads and writes users"| node_models
node_doccontroller -->|"uploads PDF"| node_cloudinary
node_doccontroller -->|"enqueues processing"| node_redis
node_server -->|"starts worker"| node_worker
node_worker -->|"consumes jobs"| node_redis
node_worker -->|"parses PDF"| node_pdfparse
node_worker -->|"creates chunks"| node_chunking
node_worker -->|"indexes chunks"| node_vectors
node_worker -->|"updates status"| node_models
node_doccontroller -->|"retrieves chunks"| node_vectors
node_vectors -->|"uses ranking"| node_bm25
node_vectors -->|"searches index"| node_chromadb
node_doccontroller -->|"passes retrieved context"| node_answer
node_answer -->|"generates answer"| node_gemini
node_doccontroller -->|"logs interaction"| node_sqlite
node_doccontroller -->|"stores chat history"| node_models
node_doccontroller -->|"deletes collection"| node_chromadb
node_evals -->|"compares strategies"| node_vectors
node_evals -->|"records scores"| node_sqlite

click node_app "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/App.jsx"
click node_authscreen "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/AuthScreen.jsx"
click node_uploadscreen "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/UploadScreen.jsx"
click node_documentscreen "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/DocumentListScreen.jsx"
click node_chatscreen "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/ChatScreen.jsx"
click node_paymentscreen "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/PaymentScreen.jsx"
click node_server "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/server.js"
click node_auth "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/controllers/authController.js"
click node_authmw "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/middleware/authMiddleware.js"
click node_doccontroller "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/controllers/documentController.js"
click node_routes "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/routes/documentRoutes.js"
click node_uploadmw "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/middleware/upload.js"
click node_worker "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/workers/pdfWorker.js"
click node_pdfparse "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/pdfService.js"
click node_chunking "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/chunkingService.js"
click node_vectors "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/vectorStore.js"
click node_bm25 "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/bm25Service.js"
click node_answer "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/llmService.js"
click node_models "https://github.com/devanshu23bcs030/rag-eval-project/tree/main/backend/src/models"
click node_sqlite "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/dbService.js"
click node_evals "https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/benchmarks/runEvals.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_app,node_authscreen,node_uploadscreen,node_documentscreen,node_chatscreen,node_paymentscreen,node_user toneBlue
class node_server,node_auth,node_authmw,node_doccontroller,node_routes,node_uploadmw,node_redis,node_chromadb toneAmber
class node_worker,node_pdfparse,node_chunking,node_vectors,node_bm25,node_answer toneMint
class node_mongo,node_models,node_sqlite toneRose
class node_evals,node_clerk,node_cloudinary,node_gemini toneIndigo
```

## Components

### User interface

- [App navigation](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in screen](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/AuthScreen.jsx): `frontend/src/components/AuthScreen.jsx`
- [Upload screen](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/UploadScreen.jsx): `frontend/src/components/UploadScreen.jsx`
- [Document list](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/DocumentListScreen.jsx): `frontend/src/components/DocumentListScreen.jsx`
- [Chat screen](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/ChatScreen.jsx): `frontend/src/components/ChatScreen.jsx`
- [Credit screen](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/frontend/src/components/PaymentScreen.jsx): `frontend/src/components/PaymentScreen.jsx`

### API and identity

- [Express API](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/server.js): `backend/src/server.js`
- [Auth controller](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [JWT authentication](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/middleware/authMiddleware.js): `backend/src/middleware/authMiddleware.js`
- [Document controller](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/controllers/documentController.js): `backend/src/controllers/documentController.js`
- [Delete route](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/routes/documentRoutes.js): `backend/src/routes/documentRoutes.js`
- [PDF upload middleware](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/middleware/upload.js): `backend/src/middleware/upload.js`

### PDF and retrieval

- [PDF worker](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/workers/pdfWorker.js): `backend/src/workers/pdfWorker.js`
- [PDF parsing](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/pdfService.js): `backend/src/services/pdfService.js`
- [Chunking strategies](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/chunkingService.js): `backend/src/services/chunkingService.js`
- [Vector and hybrid search](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/vectorStore.js): `backend/src/services/vectorStore.js`
- [BM25 ranking](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/bm25Service.js): `backend/src/services/bm25Service.js`
- [Answer generation](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/llmService.js): `backend/src/services/llmService.js`

### Data and telemetry

- **MongoDB**
- [Document, user, chat models](https://github.com/devanshu23bcs030/rag-eval-project/tree/main/backend/src/models): `backend/src/models`
- [SQLite telemetry](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/src/services/dbService.js): `backend/src/services/dbService.js`

### Retrieval evaluation

- [Strategy benchmark](https://github.com/devanshu23bcs030/rag-eval-project/blob/main/backend/benchmarks/runEvals.js): `backend/benchmarks/runEvals.js`

### Other components

- **User**
- **Clerk identity**
- **Cloudinary files**
- **Redis job queue**
- **ChromaDB index**
- **Gemini model**

## Connections

- User → App navigation: uses (evidence: `README.md`)
- App navigation → Sign-in screen: renders (evidence: `frontend/src/App.jsx`)
- App navigation → Upload screen: renders (evidence: `frontend/src/App.jsx`)
- App navigation → Document list: renders (evidence: `frontend/src/App.jsx`)
- App navigation → Chat screen: renders (evidence: `frontend/src/App.jsx`)
- App navigation → Credit screen: renders (evidence: `frontend/src/App.jsx`)
- Sign-in screen → Clerk identity: authenticates (evidence: `README.md`)
- App navigation → Express API: calls auth API (evidence: `frontend/src/App.jsx`)
- Express API → Auth controller: routes auth (evidence: `backend/src/server.js`)
- Express API → JWT authentication: guards endpoints (evidence: `backend/src/server.js`)
- Express API → Document controller: routes document API (evidence: `backend/src/server.js`)
- Express API → Delete route: mounts delete route (evidence: `backend/src/server.js`)
- Delete route → JWT authentication: guards delete (evidence: `backend/src/routes/documentRoutes.js`)
- Delete route → Document controller: dispatches delete (evidence: `backend/src/routes/documentRoutes.js`)
- Express API → PDF upload middleware: accepts PDF (evidence: `backend/src/server.js`)
- Document controller → Document, user, chat models: reads and writes (evidence: `backend/src/controllers/documentController.js`)
- Auth controller → Document, user, chat models: reads and writes users (evidence: `backend/src/controllers/authController.js`)
- Document controller → Cloudinary files: uploads PDF (evidence: `README.md`)
- Document controller → Redis job queue: enqueues processing (evidence: `backend/src/controllers/documentController.js`)
- Express API → PDF worker: starts worker (evidence: `backend/src/server.js`)
- PDF worker → Redis job queue: consumes jobs (evidence: `README.md`)
- PDF worker → PDF parsing: parses PDF (evidence: `backend/src/workers/pdfWorker.js`)
- PDF worker → Chunking strategies: creates chunks (evidence: `backend/src/workers/pdfWorker.js`)
- PDF worker → Vector and hybrid search: indexes chunks (evidence: `backend/src/workers/pdfWorker.js`)
- PDF worker → Document, user, chat models: updates status (evidence: `backend/src/workers/pdfWorker.js`)
- Document controller → Vector and hybrid search: retrieves chunks (evidence: `backend/src/controllers/documentController.js`)
- Vector and hybrid search → BM25 ranking: uses ranking (evidence: `backend/src/services/vectorStore.js`)
- Vector and hybrid search → ChromaDB index: searches index (evidence: `README.md`)
- Document controller → Answer generation: passes retrieved context (evidence: `backend/src/controllers/documentController.js`)
- Answer generation → Gemini model: generates answer (evidence: `backend/src/services/llmService.js`)
- Document controller → SQLite telemetry: logs interaction (evidence: `backend/src/controllers/documentController.js`)
- Document controller → Document, user, chat models: stores chat history (evidence: `backend/src/controllers/documentController.js`)
- Document controller → ChromaDB index: deletes collection (evidence: `backend/src/controllers/documentController.js`)
- Strategy benchmark → Vector and hybrid search: compares strategies (evidence: `README.md`)
- Strategy benchmark → SQLite telemetry: records scores (evidence: `README.md`)
