premjituri/local-rag-chat

Purpose and topology

Local RAG chat application: users upload PDF, DOCX, or TXT files, then receive answers grounded only in indexed document content. A React SPA calls a Spring Boot REST API, which uses local Ollama for embeddings/chat generation and ChromaDB for vector persistence/search. Container orchestration is in docker-compose.yml and docker-compose.chroma.yml.

Entry points and API boundary

Backend startup is backend/src/main/java/com/ragsystem/rag/RagBackendApplication.java. HTTP endpoints are split by workflow:

• Upload: backend/src/main/java/com/ragsystem/rag/controller/UploadController.java

• Question answering: backend/src/main/java/com/ragsystem/rag/controller/AskController.java

• Indexed-data readiness: backend/src/main/java/com/ragsystem/rag/controller/StatusController.java

DTOs isolate API contracts from services, including backend/src/main/java/com/ragsystem/rag/dto/AskRequest.java and backend/src/main/java/com/ragsystem/rag/dto/AskResponse.java.

Document ingestion pipeline

UploadController delegates to backend/src/main/java/com/ragsystem/rag/service/UploadService.java, which validates and persists raw uploads, extracts readable text through backend/src/main/java/com/ragsystem/rag/service/DocumentParserService.java, and passes it to backend/src/main/java/com/ragsystem/rag/service/ChunkService.java. Chunks are overlapping text segments represented by backend/src/main/java/com/ragsystem/rag/model/Chunk.java.

backend/src/main/java/com/ragsystem/rag/service/VectorStoreService.java embeds chunks through Ollama/Spring AI and writes them with metadata into ChromaDB. This is the boundary between local file handling/parsing and durable semantic indexing.

Retrieval and generation pipeline

backend/src/main/java/com/ragsystem/rag/service/AskService.java enforces upload-first behavior, retrieves top-K similar chunks through VectorStoreService, and avoids generation when no useful context is found. It sends the grounded context and user question to backend/src/main/java/com/ragsystem/rag/service/ChatService.java, which owns LLM interaction and returns the answer. The key control boundary is retrieval before generation: Chroma results determine whether Ollama’s chat model is called.

Backend integration and lifecycle

Spring AI client wiring is centralized in backend/src/main/java/com/ragsystem/rag/config/ChatClientConfig.java. Chroma tenant/database/collection provisioning and ordering are handled by backend/src/main/java/com/ragsystem/rag/config/ChromaSchemaInitializer.java and backend/src/main/java/com/ragsystem/rag/config/ChromaSchemaOrderingConfig.java; the collection uses cosine similarity. Runtime settings, including chunking, retrieval count, storage, AI endpoints/models, and upload limits, are in backend/src/main/resources/application.yml.

Cross-origin access is controlled by backend/src/main/java/com/ragsystem/rag/config/CorsConfig.java. API failures become structured HTTP responses through backend/src/main/java/com/ragsystem/rag/exception/GlobalExceptionHandler.java.

Frontend application flow

The SPA boots at frontend/src/main.jsx and renders the RAG screen from frontend/src/pages/RagChatPage.jsx. frontend/src/components/DocumentUpload.jsx uploads documents; frontend/src/components/ChatBox.jsx submits questions; frontend/src/components/AnswerSection.jsx displays generated answers. On load, the UI checks readiness via frontend/src/services/statusService.js, preserving ask availability when Chroma data already exists.

Frontend-to-backend calls are centralized in frontend/src/services/apiClient.js, with workflow-specific clients in frontend/src/services/uploadService.js and frontend/src/services/askService.js. Development proxying is configured by frontend/vite.config.js; production serving is supported by frontend/nginx.conf.

Runtime infrastructure

Required local services are Ollama (port 11434) with embedding and chat models, ChromaDB (port 8000) with on-disk vector data, the Java 21 backend (8080), and React/Vite frontend (5173 in development). Docker definitions are backend/Dockerfile, frontend/Dockerfile, and docker-compose.yml; Ollama remains a host-provided runtime in the documented container deployment.