# gokul-nishandh/vectrapdf architecture

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

- Interactive diagram: https://gitdiagram.com/gokul-nishandh/vectrapdf
- Repository: https://github.com/gokul-nishandh/vectrapdf

## Overview

#### Purpose and topology
VectraPDF is a document-intelligence platform: authenticated users upload PDFs, query/analyze them with a RAG service, and review chat/history. It is split into a React browser client, a Node/Express application API, and a Python document/RAG service. Primary entry points are `client/src/main.tsx`, `backend/src/server.js`, and `backend/service/api.py`.

#### Client application
The Vite React SPA owns user interaction, routing, and presentation for authentication, dashboard/document workflows, chat history, previews, and profile/settings. `client/src/App.tsx` composes the application; dashboard/history/preview surfaces live in `client/src/pages/Dashboard.tsx`, `client/src/pages/History.tsx`, and `client/src/pages/PDFPreview.tsx`. Shared user and PDF state cross page boundaries through `client/src/contexts/userContext.tsx` and `client/src/contexts/pdfContext.tsx`.

#### Node API boundary
Express is the main application-facing backend. `backend/src/server.js` starts the HTTP server and `backend/src/app.js` assembles middleware and route modules. It separates externally exposed concerns into authentication, user management, document/chat interaction, and history via `backend/src/routes/authRoutes.js`, `backend/src/routes/chatRoutes.js`, and `backend/src/routes/historyRoutes.js`. Controllers implement request orchestration, particularly `backend/src/controllers/authController.js` and `backend/src/controllers/chatController.js`.

#### Identity and request protection
The API supports OAuth 2.0 and JWT authentication. Passport integration is configured in `backend/src/config/passport.js`; token creation is isolated in `backend/src/utils/jwt.js`; protected routes pass through `backend/src/middlewares/authMiddleware.js`. This creates the core authorization boundary between browser requests and per-user documents/history.

#### Persistence, uploads, and chat history
PostgreSQL persistence is modeled through Prisma in `backend/prisma/schema.prisma`, with the initial schema migration at `backend/prisma/migrations/20250922182615_init/migration.sql`. Upload handling is a dedicated middleware (`backend/src/middlewares/uploadMiddleware.js`), while uploaded files are stored under the service-side filesystem hierarchy `backend/service/uploaded_pdfs/`. Redis is configured in `backend/src/config/redis.js` and is described as a write-through cache for chat-history sections.

#### RAG/document-analysis service
The Python service is a separate runtime responsible for retrieval-augmented PDF intelligence. `backend/service/api.py` exposes its service API; `backend/service/RAG/rag_system.py` contains RAG orchestration and `backend/service/RAG/vectordb.py` owns vector-store interaction. The Node chat controller is the likely integration boundary: it accepts authenticated chat/document requests, then delegates document retrieval/answer generation to this service rather than embedding RAG logic in Express.

#### Deployment and infrastructure
The browser client is intended for Vercel (`client/vercel.json`, `client/Dockerfile`); the Node API targets Render-compatible process/container deployment (`backend/Procfile`, `backend/Dockerfile`); the RAG runtime has its own container definition at `backend/service/Dockerfile`. `docker-compose.yml` supports multi-service local deployment. Material external infrastructure is Neon-hosted PostgreSQL, Redis, OAuth providers, and the vector database used by the Python RAG layer. Kafka and broader asynchronous processing are planned, not current architecture.

Main entry points: [`client/src/App.tsx`](https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/App.tsx) (App and routes), [`backend/src/routes/chatRoutes.js`](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/routes/chatRoutes.js) (Auth, chat, history routes), [`backend/src/controllers/chatController.js`](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/controllers/chatController.js) (Chat controller), [`backend/src/server.js`](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/server.js) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_spa_entry["SPA entry<br/>Vite React<br/>[main.tsx]"]
  node_client_app["App and routes<br/>React composition<br/>[App.tsx]"]
  node_document_ui["Dashboard and preview<br/>document workflow UI<br/>[Dashboard.tsx]"]
  node_history_ui["Chat history<br/>history UI<br/>[History.tsx]"]
  node_client_state["User and PDF state<br/>React contexts<br/>[userContext.tsx]"]
end

subgraph group_api["Node API"]
  node_server["HTTP server<br/>Express bootstrap<br/>[server.js]"]
  node_app["Application assembly<br/>Express middleware<br/>[app.js]"]
  node_routes["Auth, chat, history routes<br/>Express routes<br/>[chatRoutes.js]"]
  node_auth_boundary["Authentication boundary<br/>OAuth and JWT protection<br/>[authMiddleware.js]"]
  node_chat_controller["Chat controller<br/>request orchestration<br/>[chatController.js]"]
  node_upload_handler["Upload handler<br/>multipart middleware"]
end

subgraph group_rag["Python RAG Service"]
  node_rag_api{{"RAG service API<br/>Python service<br/>[api.py]"}}
  node_rag_orchestrator["RAG orchestration<br/>retrieval and generation<br/>[rag_system.py]"]
  node_vector_store["Vector store adapter<br/>vector retrieval<br/>[vectordb.py]"]
end

subgraph group_data["Data &amp; Infrastructure"]
  node_uploads[("Uploaded PDFs<br/>service filesystem")]
  node_postgres[("PostgreSQL<br/>Neon persistence<br/>[schema.prisma]")]
  node_redis[("Redis cache<br/>chat-history cache<br/>[redis.js]")]
  node_oauth(("OAuth providers<br/>external identity"))
  node_vector_db[("Vector database<br/>external vector storage")]
  node_compose["Local multi-service deployment<br/>Docker Compose<br/>[docker-compose.yml]"]
end

node_spa_entry -->|"mounts"| node_client_app
node_client_app -->|"routes to"| node_document_ui
node_client_app -->|"routes to"| node_history_ui
node_client_app -->|"uses"| node_client_state
node_document_ui -->|"authenticated API requests"| node_server
node_history_ui -->|"history requests"| node_server
node_server -->|"starts"| node_app
node_app -->|"mounts"| node_routes
node_routes -->|"protects requests"| node_auth_boundary
node_auth_boundary -->|"authenticates with"| node_oauth
node_routes -->|"dispatches chat"| node_chat_controller
node_routes -->|"handles uploads"| node_upload_handler
node_chat_controller -->|"delegates RAG"| node_rag_api
node_chat_controller -->|"persists data"| node_postgres
node_chat_controller -->|"reads and writes history cache"| node_redis
node_upload_handler -->|"stores PDFs"| node_uploads
node_rag_api -->|"invokes"| node_rag_orchestrator
node_rag_orchestrator -->|"retrieves through"| node_vector_store
node_vector_store -->|"queries"| node_vector_db
node_rag_orchestrator -->|"reads documents"| node_uploads
node_compose -.->|"runs locally"| node_server
node_compose -.->|"runs locally"| node_rag_api

click node_spa_entry "https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/main.tsx"
click node_client_app "https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/App.tsx"
click node_document_ui "https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/pages/Dashboard.tsx"
click node_history_ui "https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/pages/History.tsx"
click node_client_state "https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/contexts/userContext.tsx"
click node_server "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/server.js"
click node_app "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/app.js"
click node_routes "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/routes/chatRoutes.js"
click node_auth_boundary "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/middlewares/authMiddleware.js"
click node_chat_controller "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/controllers/chatController.js"
click node_upload_handler "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/middlewares/uploadMiddleware.js"
click node_rag_api "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/service/api.py"
click node_rag_orchestrator "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/service/RAG/rag_system.py"
click node_vector_store "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/service/RAG/vectordb.py"
click node_postgres "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/prisma/schema.prisma"
click node_redis "https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/config/redis.js"
click node_compose "https://github.com/gokul-nishandh/vectrapdf/blob/main/docker-compose.yml"

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_spa_entry,node_client_app,node_document_ui,node_history_ui,node_client_state toneBlue
class node_server,node_app,node_routes,node_auth_boundary,node_chat_controller,node_upload_handler toneAmber
class node_rag_api,node_rag_orchestrator,node_vector_store toneMint
class node_uploads,node_postgres,node_redis,node_oauth,node_vector_db,node_compose toneRose
```

## Components

### React Client

- [SPA entry](https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/main.tsx): Vite React · `client/src/main.tsx`
- [App and routes](https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/App.tsx): React composition · `client/src/App.tsx`
- [Dashboard and preview](https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/pages/Dashboard.tsx): document workflow UI · `client/src/pages/Dashboard.tsx`
- [Chat history](https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/pages/History.tsx): history UI · `client/src/pages/History.tsx`
- [User and PDF state](https://github.com/gokul-nishandh/vectrapdf/blob/main/client/src/contexts/userContext.tsx): React contexts · `client/src/contexts/userContext.tsx`

### Node API

- [HTTP server](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/server.js): Express bootstrap · `backend/src/server.js`
- [Application assembly](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/app.js): Express middleware · `backend/src/app.js`
- [Auth, chat, history routes](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/routes/chatRoutes.js): Express routes · `backend/src/routes/chatRoutes.js`
- [Authentication boundary](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/middlewares/authMiddleware.js): OAuth and JWT protection · Passport, JWT issuance, and protected-route middleware. · `backend/src/middlewares/authMiddleware.js`
- [Chat controller](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/controllers/chatController.js): request orchestration · `backend/src/controllers/chatController.js`
- [Upload handler](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/middlewares/uploadMiddleware.js): multipart middleware · `backend/src/middlewares/uploadMiddleware.js`

### Python RAG Service

- [RAG service API](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/service/api.py): Python service · `backend/service/api.py`
- [RAG orchestration](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/service/RAG/rag_system.py): retrieval and generation · `backend/service/RAG/rag_system.py`
- [Vector store adapter](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/service/RAG/vectordb.py): vector retrieval · `backend/service/RAG/vectordb.py`

### Data & Infrastructure

- **Uploaded PDFs**: service filesystem
- [PostgreSQL](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/prisma/schema.prisma): Neon persistence · Prisma-managed users, documents, and history. · `backend/prisma/schema.prisma`
- [Redis cache](https://github.com/gokul-nishandh/vectrapdf/blob/main/backend/src/config/redis.js): chat-history cache · Write-through cache for chat-history sections. · `backend/src/config/redis.js`
- **OAuth providers**: external identity
- **Vector database**: external vector storage
- [Local multi-service deployment](https://github.com/gokul-nishandh/vectrapdf/blob/main/docker-compose.yml): Docker Compose · `docker-compose.yml`

## Connections

- SPA entry → App and routes: mounts
- App and routes → Dashboard and preview: routes to
- App and routes → Chat history: routes to
- App and routes → User and PDF state: uses
- Dashboard and preview → HTTP server: authenticated API requests
- Chat history → HTTP server: history requests
- HTTP server → Application assembly: starts
- Application assembly → Auth, chat, history routes: mounts
- Auth, chat, history routes → Authentication boundary: protects requests
- Authentication boundary → OAuth providers: authenticates with
- Auth, chat, history routes → Chat controller: dispatches chat
- Auth, chat, history routes → Upload handler: handles uploads
- Chat controller → RAG service API: delegates RAG
- Chat controller → PostgreSQL: persists data
- Chat controller → Redis cache: reads and writes history cache
- Upload handler → Uploaded PDFs: stores PDFs
- RAG service API → RAG orchestration: invokes
- RAG orchestration → Vector store adapter: retrieves through
- Vector store adapter → Vector database: queries
- RAG orchestration → Uploaded PDFs: reads documents
- Local multi-service deployment → HTTP server: runs locally
- Local multi-service deployment → RAG service API: runs locally
