# goeldivya2/karya- architecture

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

- Interactive diagram: https://gitdiagram.com/goeldivya2/karya-
- Repository: https://github.com/goeldivya2/karya-

## Overview

Karya is a collaborative document Q&A backend. Users authenticate, create or join rooms, upload PDFs, and ask room-scoped questions; the backend processes documents into searchable vectors and uses retrieved context to generate answers. MongoDB holds users, rooms, documents, and question history, while Socket.IO broadcasts document and question events. The README documents the full RAG stages; several service files were not excerpted, so those pipeline links rely on that documentation.

Main entry points: [`backend/controllers/documentController.js`](https://github.com/goeldivya2/karya-/blob/main/backend/controllers/documentController.js) (Document lifecycle), [`backend/controllers/questionController.js`](https://github.com/goeldivya2/karya-/blob/main/backend/controllers/questionController.js) (Question answering), [`backend/app.js`](https://github.com/goeldivya2/karya-/blob/main/backend/app.js) (HTTP app), [`backend/server.js`](https://github.com/goeldivya2/karya-/blob/main/backend/server.js) (HTTP and socket server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["HTTP app<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_auth_controller["Authentication<br/>[authController.js]"]
  node_auth_middleware["JWT access<br/>[authMiddleware.js]"]
  node_server["HTTP and socket server<br/>[server.js]"]
end

subgraph group_workspace["Collaborative rooms"]
  node_room_routes["Room routes<br/>[roomRoutes.js]"]
  node_room_controller["Room management<br/>[roomController.js]"]
end

subgraph group_documents["Document ingestion"]
  node_document_routes["Document routes<br/>[documentRoutes.js]"]
  node_upload_middleware["PDF upload"]
  node_document_controller["Document lifecycle"]
  node_pdf_processor["PDF extraction<br/>[pdfProcessor.js]"]
  node_chunk_service["Text chunking<br/>[chunkService.js]"]
end

subgraph group_rag["Question answering"]
  node_embedding_service["Embedding generation"]
  node_pinecone_service["Vector operations<br/>[pineconeService.js]"]
  node_question_routes["Question routes<br/>[questionRoutes.js]"]
  node_question_controller["Question answering"]
  node_llm_service["Answer generation<br/>[llmService.js]"]
end

subgraph group_realtime["Persistence and events"]
  node_user_model[("User records<br/>[User.js]")]
  node_room_model[("Room records<br/>[Room.js]")]
  node_document_model[("Document records<br/>[Documents.js]")]
  node_question_model[("Question history<br/>[Question.js]")]
  node_db_config["MongoDB connection<br/>[db.js]"]
  node_pinecone_config["Pinecone client<br/>[pinecone.js]"]
  node_socket_module["Socket access<br/>[socket.js]"]
  node_socket_handler["Socket events<br/>[socketHandler.js]"]
end

node_user(("User"))
node_mongodb[("MongoDB")]
node_pinecone[("Pinecone")]
node_gemini["Google Gemini"]
node_socket_clients(("Room participants"))

node_user -->|"sends requests"| node_app
node_app -->|"mounts"| node_auth_routes
node_app -->|"mounts"| node_room_routes
node_app -->|"mounts"| node_document_routes
node_app -->|"mounts"| node_question_routes
node_auth_routes -->|"routes to"| node_auth_controller
node_room_routes -->|"routes to"| node_room_controller
node_document_routes -->|"routes to"| node_document_controller
node_document_routes -->|"accepts file"| node_upload_middleware
node_question_routes -->|"routes to"| node_question_controller
node_room_routes -->|"checks JWT"| node_auth_middleware
node_document_routes -->|"checks JWT"| node_auth_middleware
node_question_routes -->|"checks JWT"| node_auth_middleware
node_auth_controller -->|"uses"| node_user_model
node_room_controller -->|"reads and writes"| node_room_model
node_document_controller -->|"checks membership"| node_room_model
node_document_controller -->|"creates and deletes"| node_document_model
node_document_controller -->|"extracts text"| node_pdf_processor
node_pdf_processor -->|"provides text"| node_chunk_service
node_document_controller -->|"chunks text"| node_chunk_service
node_document_controller -->|"embeds chunks"| node_embedding_service
node_document_controller -->|"stores or deletes"| node_pinecone_service
node_embedding_service -->|"requests embeddings"| node_gemini
node_pinecone_service -->|"uses client"| node_pinecone_config
node_pinecone_service -->|"queries vectors"| node_pinecone
node_question_controller -->|"checks membership"| node_room_model
node_question_controller -->|"embeds question"| node_embedding_service
node_question_controller -->|"retrieves chunks"| node_pinecone_service
node_question_controller -->|"generates answer"| node_llm_service
node_llm_service -->|"invokes model"| node_gemini
node_question_controller -->|"saves and reads"| node_question_model
node_server -->|"serves"| node_app
node_server -->|"connects database"| node_db_config
node_db_config -->|"connects"| node_mongodb
node_server -->|"initializes events"| node_socket_handler
node_server -->|"sets socket"| node_socket_module
node_document_controller -->|"broadcasts document events"| node_socket_module
node_question_controller -->|"broadcasts questions"| node_socket_module
node_socket_handler -->|"supports real-time collaboration"| node_socket_clients

click node_app "https://github.com/goeldivya2/karya-/blob/main/backend/app.js"
click node_auth_routes "https://github.com/goeldivya2/karya-/blob/main/backend/routes/authRoutes.js"
click node_auth_controller "https://github.com/goeldivya2/karya-/blob/main/backend/controllers/authController.js"
click node_auth_middleware "https://github.com/goeldivya2/karya-/blob/main/backend/middleware/authMiddleware.js"
click node_room_routes "https://github.com/goeldivya2/karya-/blob/main/backend/routes/roomRoutes.js"
click node_room_controller "https://github.com/goeldivya2/karya-/blob/main/backend/controllers/roomController.js"
click node_document_routes "https://github.com/goeldivya2/karya-/blob/main/backend/routes/documentRoutes.js"
click node_upload_middleware "https://github.com/goeldivya2/karya-/blob/main/backend/middleware/uploadMiddleware.js"
click node_document_controller "https://github.com/goeldivya2/karya-/blob/main/backend/controllers/documentController.js"
click node_pdf_processor "https://github.com/goeldivya2/karya-/blob/main/backend/services/pdfProcessor.js"
click node_chunk_service "https://github.com/goeldivya2/karya-/blob/main/backend/services/chunkService.js"
click node_embedding_service "https://github.com/goeldivya2/karya-/blob/main/backend/services/embeddingService.js"
click node_pinecone_service "https://github.com/goeldivya2/karya-/blob/main/backend/services/pineconeService.js"
click node_question_routes "https://github.com/goeldivya2/karya-/blob/main/backend/routes/questionRoutes.js"
click node_question_controller "https://github.com/goeldivya2/karya-/blob/main/backend/controllers/questionController.js"
click node_llm_service "https://github.com/goeldivya2/karya-/blob/main/backend/services/llmService.js"
click node_user_model "https://github.com/goeldivya2/karya-/blob/main/backend/models/User.js"
click node_room_model "https://github.com/goeldivya2/karya-/blob/main/backend/models/Room.js"
click node_document_model "https://github.com/goeldivya2/karya-/blob/main/backend/models/Documents.js"
click node_question_model "https://github.com/goeldivya2/karya-/blob/main/backend/models/Question.js"
click node_db_config "https://github.com/goeldivya2/karya-/blob/main/backend/config/db.js"
click node_pinecone_config "https://github.com/goeldivya2/karya-/blob/main/backend/config/pinecone.js"
click node_socket_module "https://github.com/goeldivya2/karya-/blob/main/backend/sockets/socket.js"
click node_socket_handler "https://github.com/goeldivya2/karya-/blob/main/backend/sockets/socketHandler.js"
click node_server "https://github.com/goeldivya2/karya-/blob/main/backend/server.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_auth_routes,node_auth_controller,node_auth_middleware,node_server,node_user toneBlue
class node_room_routes,node_room_controller,node_mongodb,node_pinecone toneAmber
class node_document_routes,node_upload_middleware,node_document_controller,node_pdf_processor,node_chunk_service toneMint
class node_embedding_service,node_pinecone_service,node_question_routes,node_question_controller,node_llm_service toneRose
class node_user_model,node_room_model,node_document_model,node_question_model,node_db_config,node_pinecone_config,node_socket_module,node_socket_handler,node_gemini,node_socket_clients toneIndigo
```

## Components

### API and access

- [HTTP app](https://github.com/goeldivya2/karya-/blob/main/backend/app.js): `backend/app.js`
- [Auth routes](https://github.com/goeldivya2/karya-/blob/main/backend/routes/authRoutes.js): `backend/routes/authRoutes.js`
- [Authentication](https://github.com/goeldivya2/karya-/blob/main/backend/controllers/authController.js): `backend/controllers/authController.js`
- [JWT access](https://github.com/goeldivya2/karya-/blob/main/backend/middleware/authMiddleware.js): `backend/middleware/authMiddleware.js`
- [HTTP and socket server](https://github.com/goeldivya2/karya-/blob/main/backend/server.js): `backend/server.js`

### Collaborative rooms

- [Room routes](https://github.com/goeldivya2/karya-/blob/main/backend/routes/roomRoutes.js): `backend/routes/roomRoutes.js`
- [Room management](https://github.com/goeldivya2/karya-/blob/main/backend/controllers/roomController.js): `backend/controllers/roomController.js`

### Document ingestion

- [Document routes](https://github.com/goeldivya2/karya-/blob/main/backend/routes/documentRoutes.js): `backend/routes/documentRoutes.js`
- [PDF upload](https://github.com/goeldivya2/karya-/blob/main/backend/middleware/uploadMiddleware.js): `backend/middleware/uploadMiddleware.js`
- [Document lifecycle](https://github.com/goeldivya2/karya-/blob/main/backend/controllers/documentController.js): `backend/controllers/documentController.js`
- [PDF extraction](https://github.com/goeldivya2/karya-/blob/main/backend/services/pdfProcessor.js): `backend/services/pdfProcessor.js`
- [Text chunking](https://github.com/goeldivya2/karya-/blob/main/backend/services/chunkService.js): `backend/services/chunkService.js`

### Question answering

- [Embedding generation](https://github.com/goeldivya2/karya-/blob/main/backend/services/embeddingService.js): `backend/services/embeddingService.js`
- [Vector operations](https://github.com/goeldivya2/karya-/blob/main/backend/services/pineconeService.js): `backend/services/pineconeService.js`
- [Question routes](https://github.com/goeldivya2/karya-/blob/main/backend/routes/questionRoutes.js): `backend/routes/questionRoutes.js`
- [Question answering](https://github.com/goeldivya2/karya-/blob/main/backend/controllers/questionController.js): `backend/controllers/questionController.js`
- [Answer generation](https://github.com/goeldivya2/karya-/blob/main/backend/services/llmService.js): `backend/services/llmService.js`

### Persistence and events

- [User records](https://github.com/goeldivya2/karya-/blob/main/backend/models/User.js): `backend/models/User.js`
- [Room records](https://github.com/goeldivya2/karya-/blob/main/backend/models/Room.js): `backend/models/Room.js`
- [Document records](https://github.com/goeldivya2/karya-/blob/main/backend/models/Documents.js): `backend/models/Documents.js`
- [Question history](https://github.com/goeldivya2/karya-/blob/main/backend/models/Question.js): `backend/models/Question.js`
- [MongoDB connection](https://github.com/goeldivya2/karya-/blob/main/backend/config/db.js): `backend/config/db.js`
- [Pinecone client](https://github.com/goeldivya2/karya-/blob/main/backend/config/pinecone.js): `backend/config/pinecone.js`
- [Socket access](https://github.com/goeldivya2/karya-/blob/main/backend/sockets/socket.js): `backend/sockets/socket.js`
- [Socket events](https://github.com/goeldivya2/karya-/blob/main/backend/sockets/socketHandler.js): `backend/sockets/socketHandler.js`

### Other components

- **User**
- **MongoDB**
- **Pinecone**
- **Google Gemini**
- **Room participants**

## Connections

- User → HTTP app: sends requests (evidence: `README.md`)
- HTTP app → Auth routes: mounts (evidence: `backend/app.js`)
- HTTP app → Room routes: mounts (evidence: `backend/app.js`)
- HTTP app → Document routes: mounts (evidence: `backend/app.js`)
- HTTP app → Question routes: mounts (evidence: `backend/app.js`)
- Auth routes → Authentication: routes to (evidence: `backend/routes/authRoutes.js`)
- Room routes → Room management: routes to (evidence: `backend/routes/roomRoutes.js`)
- Document routes → Document lifecycle: routes to (evidence: `backend/routes/documentRoutes.js`)
- Document routes → PDF upload: accepts file (evidence: `backend/routes/documentRoutes.js`)
- Question routes → Question answering: routes to (evidence: `backend/routes/questionRoutes.js`)
- Room routes → JWT access: checks JWT (evidence: `backend/routes/roomRoutes.js`)
- Document routes → JWT access: checks JWT (evidence: `backend/routes/documentRoutes.js`)
- Question routes → JWT access: checks JWT (evidence: `backend/routes/questionRoutes.js`)
- Authentication → User records: uses (evidence: `backend/controllers/authController.js`)
- Room management → Room records: reads and writes (evidence: `backend/controllers/roomController.js`)
- Document lifecycle → Room records: checks membership (evidence: `backend/controllers/documentController.js`)
- Document lifecycle → Document records: creates and deletes (evidence: `backend/controllers/documentController.js`)
- Document lifecycle → PDF extraction: extracts text (evidence: `backend/controllers/documentController.js`)
- PDF extraction → Text chunking: provides text (evidence: `README.md`)
- Document lifecycle → Text chunking: chunks text (evidence: `backend/controllers/documentController.js`)
- Document lifecycle → Embedding generation: embeds chunks (evidence: `backend/controllers/documentController.js`)
- Document lifecycle → Vector operations: stores or deletes (evidence: `backend/controllers/documentController.js`)
- Embedding generation → Google Gemini: requests embeddings (evidence: `backend/services/embeddingService.js`)
- Vector operations → Pinecone client: uses client (evidence: `backend/services/pineconeService.js`)
- Vector operations → Pinecone: queries vectors (evidence: `README.md`)
- Question answering → Room records: checks membership (evidence: `backend/controllers/questionController.js`)
- Question answering → Embedding generation: embeds question (evidence: `backend/controllers/questionController.js`)
- Question answering → Vector operations: retrieves chunks (evidence: `backend/controllers/questionController.js`)
- Question answering → Answer generation: generates answer (evidence: `backend/controllers/questionController.js`)
- Answer generation → Google Gemini: invokes model (evidence: `backend/services/llmService.js`)
- Question answering → Question history: saves and reads (evidence: `backend/controllers/questionController.js`)
- HTTP and socket server → HTTP app: serves (evidence: `backend/server.js`)
- HTTP and socket server → MongoDB connection: connects database (evidence: `backend/server.js`)
- MongoDB connection → MongoDB: connects (evidence: `README.md`)
- HTTP and socket server → Socket events: initializes events (evidence: `backend/server.js`)
- HTTP and socket server → Socket access: sets socket (evidence: `backend/server.js`)
- Document lifecycle → Socket access: broadcasts document events (evidence: `backend/controllers/documentController.js`)
- Question answering → Socket access: broadcasts questions (evidence: `backend/controllers/questionController.js`)
- Socket events → Room participants: supports real-time collaboration (evidence: `README.md`)
