How gokul-nishandh/vectrapdf works
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: App.tsx App and routes · chatRoutes.js Auth, chat, history routes · chatController.js Chat controller · server.js HTTP server
Components 20
React Client
- SPA entry
client/src/main.tsx - App and routes
client/src/App.tsx - Dashboard and preview
client/src/pages/Dashboard.tsx - Chat history
client/src/pages/History.tsx - User and PDF state
client/src/contexts/userContext.tsx
Node API
- HTTP server
backend/src/server.js - Application assembly
backend/src/app.js - Auth, chat, history routes
backend/src/routes/chatRoutes.js - Authentication boundary · Passport, JWT issuance, and protected-route middleware.
backend/src/middlewares/authMiddleware.js - Chat controller
backend/src/controllers/chatController.js - Upload handler
backend/src/middlewares/uploadMiddleware.js
Python RAG Service
- RAG service API
backend/service/api.py - RAG orchestration
backend/service/RAG/rag_system.py - Vector store adapter
backend/service/RAG/vectordb.py
Data & Infrastructure
- Uploaded PDFs
- PostgreSQL · Prisma-managed users, documents, and history.
backend/prisma/schema.prisma - Redis cache · Write-through cache for chat-history sections.
backend/src/config/redis.js - OAuth providers
- Vector database
- Local multi-service deployment
docker-compose.yml
Connections 22
- 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