XLR8 is a microservices-based backend system that enables users to upload documents, process them into embeddings, and interact with them through an AI-powered chat interface. The system is built around a Retrieval-Augmented Generation (RAG) pipeline, allowing responses to be grounded strictly in user-provided data.
At a high level, the system consists of a frontend that communicates with an API Gateway. The gateway handles authentication and routes requests to different backend services. Each service is responsible for a specific domain such as user management, document handling, chat orchestration, and message storage.
The backend integrates with external systems including PostgreSQL (with PGVector), Redis, Cloudinary, and Google Gemini for embeddings and language model responses.
The request flow follows a gateway-centric design:
Frontend → API Gateway → Microservices → External Services
The core services include:
- User Service for authentication and user management
- Upload Service for handling document uploads and embedding generation
- Chat Service for orchestrating RAG-based conversations
- Message Service for storing and retrieving chat history
The API Gateway acts as the single entry point and injects authenticated user context into downstream services.
Users begin by registering and logging in. Authentication is handled using JWT tokens stored in HTTP-only cookies. Once authenticated, all requests pass through the API Gateway, which verifies tokens and injects user information into request headers.
When a document is uploaded, it is first stored in Cloudinary. The system then processes the document by splitting it into chunks and generating embeddings using a language model. These embeddings are stored in PostgreSQL using PGVector, enabling efficient similarity search.
The chat functionality is built on top of this vector database. When a user asks a question, the Chat Service retrieves relevant document chunks based on semantic similarity. These chunks are combined with recent chat history to construct a prompt, which is then sent to the language model. The response is streamed back to the client in real time.
The retrieval and generation pipeline works as follows:
- A user sends a query through the chat interface
- The Chat Service retrieves recent messages from the Message Service
- It performs a similarity search on stored embeddings to get relevant document chunks
- A prompt is constructed using both retrieved context and recent conversation history
- The prompt is sent to the language model
- The response is streamed back to the client
- The final response is stored in the Message Service
This approach ensures that answers are grounded in user data and reduces hallucination.
Authentication is centralized in the API Gateway. Tokens are stored as HTTP-only cookies, so the frontend does not need to manually manage them. For every protected route, the gateway verifies the token and attaches a serialized user object in the x-user header.
Downstream services rely on this header instead of re-validating tokens, simplifying service logic and reducing duplication.
Backend
- Node.js, Express
- MongoDB (users, chats, metadata)
- PostgreSQL + PGVector (vector storage)
- Redis (caching)
- Multer (file uploads)
AI / RAG
- Google Gemini (LLM + embeddings)
- LangChain (document loading, chunking, vector store integration)
Infrastructure
- API Gateway (routing + authentication)
- Cloudinary (file storage)
The system uses Server-Sent Events (SSE) for streaming responses from the chat endpoint. This allows token-by-token delivery of model output and improves perceived responsiveness.
All frontend requests must include credentials so that cookies are sent automatically. The frontend should not manually attach authentication tokens or the x-user header, as these are handled by the API Gateway.
To run the project locally, clone the repository and install dependencies for each service. Configure environment variables for MongoDB, PostgreSQL, Redis, Cloudinary, and the Gemini API. Each service can then be started independently.
The system can be extended by introducing asynchronous processing for document embeddings, improving scalability through message queues, and replacing SSE with WebSockets for more robust real-time communication. Additional improvements may include multi-document querying, access control mechanisms, and production-grade monitoring.
XLR8 is a production-oriented backend system that demonstrates microservices architecture, distributed system design, and practical integration of AI models. It combines document processing, vector search, and real-time streaming into a cohesive platform that reflects real-world backend engineering challenges.