{"id":51569621,"url":"https://github.com/toozuuu/rag-assistant","last_synced_at":"2026-07-10T18:32:39.856Z","repository":{"id":361916440,"uuid":"1252564871","full_name":"toozuuu/rag-assistant","owner":"toozuuu","description":"A local, secure, and visual RAG (Retrieval-Augmented Generation) assistant built with Spring Boot 3 (Spring AI), React (Vite), and Qdrant. Runs entirely offline via Ollama to extract text and embedded screenshots/images from documents with strict anti-hallucination guards.","archived":false,"fork":false,"pushed_at":"2026-06-10T20:55:20.000Z","size":1666,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-10T22:21:55.730Z","etag":null,"topics":["document-intelligence","document-parser","generative-ai","glassmorphism","java","java-spring","local-llm","multimodal-rag","offline-ai","ollama","private-ai","qdrant","rag","react","search-engine","spring-ai","spring-boot","spring-boot-3","vector-database","vite"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toozuuu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T16:41:42.000Z","updated_at":"2026-06-10T20:55:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/toozuuu/rag-assistant","commit_stats":null,"previous_names":["toozuuu/rag-assistant"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/toozuuu/rag-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toozuuu%2Frag-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toozuuu%2Frag-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toozuuu%2Frag-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toozuuu%2Frag-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toozuuu","download_url":"https://codeload.github.com/toozuuu/rag-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toozuuu%2Frag-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35339931,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document-intelligence","document-parser","generative-ai","glassmorphism","java","java-spring","local-llm","multimodal-rag","offline-ai","ollama","private-ai","qdrant","rag","react","search-engine","spring-ai","spring-boot","spring-boot-3","vector-database","vite"],"created_at":"2026-07-10T18:32:39.635Z","updated_at":"2026-07-10T18:32:39.832Z","avatar_url":"https://github.com/toozuuu.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI-Powered RAG Assistant with Screenshot Integration\n\nA highly secure, offline-first, and **multimodal-ready RAG** (Retrieval-Augmented Generation) assistant. Engineered with **Spring Boot 3 (Spring AI)**, **React 18 (Vite)**, and a **Qdrant Vector Database**, it runs entirely locally using **Ollama**. The application stands out by extracting both plain text and embedded illustrations, screenshots, and diagrams from documents, letting the AI ground its responses with high fidelity and display visual evidence alongside answers.\n\n---\n\n## System Architecture\n\nThis system is built as a three-tier local architecture. It processes, embeds, indexes, and queries documents completely within your machine's perimeter.\n\n```mermaid\ngraph TD\n    %% Styling\n    classDef default fill:#1a1b26,stroke:#7aa2f7,stroke-width:2px,color:#a9b1d6;\n    classDef frontend fill:#1f2335,stroke:#7dcfff,stroke-width:2px,color:#7dcfff;\n    classDef backend fill:#1f2335,stroke:#9ece6a,stroke-width:2px,color:#9ece6a;\n    classDef database fill:#1f2335,stroke:#e0af68,stroke-width:2px,color:#e0af68;\n    classDef ollama fill:#1f2335,stroke:#f7768e,stroke-width:2px,color:#f7768e;\n    classDef cloud fill:#1f2335,stroke:#bb9af7,stroke-width:2px,color:#bb9af7;\n\n    subgraph Client[\"Client Tier (React \u0026 Vite)\"]\n        UI[\"React Web App (Glassmorphism Layout)\"]:::frontend\n    end\n\n    subgraph Server[\"Application Tier (Spring Boot 3)\"]\n        SecurityFilter[\"Spring Security \u0026 JWT Filter\"]:::backend\n        Controller[\"Upload \u0026 Chat Controllers\"]:::backend\n        Extractor[\"Document Processing Suite \u003cbr/\u003e(Apache Tika + PDFBox / POI)\"]:::backend\n        AIService[\"Spring AI Integration Layer\"]:::backend\n        ImgStore[\"Local Image Upload Store\"]:::backend\n    end\n\n    subgraph DataInf[\"Data \u0026 Inference Tier\"]\n        VectorDB[(\"Qdrant Vector Database\")]:::database\n        LocalInf[\"Local Inference \u003cbr/\u003e(Ollama: phi3:mini / nomic-embed)\"]:::ollama\n        CloudInf[\"Cloud/Hybrid Inference \u003cbr/\u003e(OpenRouter / OpenAI Cloud APIs)\"]:::cloud\n    end\n\n    %% Ingestion Flow\n    UI --\u003e|1. Drag-and-Drop Documents| SecurityFilter\n    SecurityFilter --\u003e|2. Authorize Request| Controller\n    Controller --\u003e|3. Ingest stream| Extractor\n    Controller --\u003e|4a. Extract plain text chunks| AIService\n    Extractor --\u003e|4b. Carve embedded screenshots/images| ImgStore\n    AIService --\u003e|5. Generate Vector Embeddings| LocalInf\n    AIService --\u003e|5. Generate Vector Embeddings| CloudInf\n    AIService --\u003e|6. Index text + payload metadata| VectorDB\n    ImgStore -.-\u003e|Link paths in payload| VectorDB\n\n    %% RAG Query Flow\n    UI --\u003e|7. Ask Natural Language Query| SecurityFilter\n    SecurityFilter --\u003e|8. Authorize Request| Controller\n    Controller --\u003e|9. Forward prompt| AIService\n    AIService --\u003e|10. Fetch relevant document chunks| VectorDB\n    VectorDB --\u003e|11. Returns top matches \u0026 image paths| AIService\n    AIService --\u003e|12. Feed query + context to LLM| LocalInf\n    AIService --\u003e|12. Feed query + context to LLM| CloudInf\n    LocalInf --\u003e|13. Generate grounded answer| AIService\n    CloudInf --\u003e|13. Generate grounded answer| AIService\n    AIService --\u003e|14. Return structured JSON answer with sources and images| UI\n```\n\n---\n\n## Why This Technology Stack?\n\nEvery element in this architecture is selected to deliver maximum privacy, lightning-fast processing, and enterprise-grade extensibility on consumer-grade hardware.\n\n| Technology | Role | Why We Selected It |\n| :--- | :--- | :--- |\n| **Spring Boot 3 \u0026 Spring AI** | Backend Framework | Spring Boot 3 brings unmatched type-safety, rapid dependency injection, and native compilation capabilities to enterprise Java. **Spring AI** abstracts vector store operations, prompt engineering, and LLM integrations cleanly, allowing us to swap components or models with zero changes to core business logic. |\n| **React 18 \u0026 Vite** | Frontend Interface | Vite delivers instantaneous Hot Module Replacement (HMR) and highly optimized production builds. React 18 allows us to create a premium, responsive glassmorphism UI with smooth asynchronous states during heavy document uploads and real-time streaming chat rendering. |\n| **Qdrant Vector Database** | Vector Indexing | Written in Rust, Qdrant is an ultra-fast vector database engineered for production. It allows us to perform high-speed cosine similarity searches, and seamlessly supports complex payload filtering (allowing us to bind document metadata, sections, and extracted screenshot paths directly to the text vectors). |\n| **Ollama (`phi3:mini` \u0026 `nomic-embed-text`)** | Local Inference | Ollama runs AI models locally on your CPU/GPU. **`nomic-embed-text`** provides high-quality 8192 token-context embeddings, and **`phi3:mini`** is an exceptionally powerful, lightweight 3.8B parameter instruct model. This ensures **100% data privacy** and **zero API costs**. |\n| **Apache Tika \u0026 PDFBox / POI** | Content Extraction Suite | **Apache Tika** handles multi-format parsing (PDF, DOCX, TXT, HTML) under a unified interface. **Apache PDFBox** and **Apache POI** carve out embedded screenshots, illustrations, and figures directly from the binary layouts of PDFs and Word documents, enabling our multimodal-like pipeline. |\n\n---\n\n## Key Features\n\n* **Grounded Inline Citations (Next-Gen Transparency)**: Replaces \"black-box\" responses. AI answers are annotated with inline citation markers like `[1]` matching dotted underlines. Hovering displays a glassmorphic tooltip containing the exact document source, page number, and original grounding context snippet.\n* **Generative Document Writer \u0026 Exporter**: Features a dedicated, in-context technical drafting editor. Offers quick-pick templates (SLA Agreement, Tech Spec, Project Roadmap, Privacy Policy) and outputs beautifully styled drafts. Exporters run 100% offline via client-side Blob downloads and custom serif Print-to-PDF framers.\n* **High-Fidelity Motion Animations (`motion.dev`)**: Fluid, physics-based transitions driven by Framer Motion. Features glide-sliding active mode pills with spring physics, enter/exit sliding list elements inside the files hub, staggered mounting chat bubbles, and rotating smooth grounding accordion logs.\n* **Perfect Viewport Height Lock \u0026 Layout Integrity**: Restricts workspace height dynamically to ensure a zero-scrollbar desktop-grade experience. Features stacked two-row file cards to eliminate text clipping or metadata badge overlaps, and isolates scrolling strictly to the ingested file lists.\n* **Token-Refresh Auto-Retry Resiliency**: An automatic interceptor that catches any `401 Unauthorized` or `403 Forbidden` API responses, silently fetches a fresh signed JWT session from the backend, and transparently retries the failed API call. Also features proactive token validation on mount to guarantee a zero-interruption browser refresh experience.\n* **Isolated Multi-Workspaces (Qdrant Vector Pools)**: Segregates documents securely. Integrates Spring AI's `.withFilterExpression(\"workspace == ...\")` payload queries in Qdrant, enabling isolated workspace swaps with instant context transitions.\n* **Visual RAG Pipeline**: Ingests PDFs and DOCXs, automatically carves out embedded illustrations and screenshots, and showcases them in a lightbox gallery inside AI answers.\n* **Self-Correction Relevance Grader (Corrective RAG)**: Features a strict anti-hallucination guard that runs a rapid corrective grading step, gracefully refusing to answer if matching ground-truth is missing.\n* **Mobile-First Responsive UX**: Employs a tailored, modern Outfit + Inter design system. Adapts cleanly across screens: full rows on Web, sliding drawer workspaces on Tablets, and touch bottom navigation bars on Mobile.\n* **Search Engine Optimized (SEO)**: Built with search-crawling directives, robot indexes, structured title tags, semantic markup, and descriptive meta keywords.\n\n---\n\n## Setup \u0026 Execution\n\n### 1. Download Local AI Models\nOpen a terminal on your host machine and run the following commands to pull the necessary models via Ollama:\n```bash\n# Pull the instruction-tuned chat model\nollama pull phi3:mini\n\n# Pull the text embedding model\nollama pull nomic-embed-text\n```\n\n### 2. Launch the Application Stack\nFrom the project root directory, run Docker Compose to build and spin up the frontend, backend, and Qdrant container:\n```bash\ndocker-compose up --build\n```\n\n### 3. Access Services\n* **Web App UI**: `http://localhost:5173/` (or port 80 if running production Nginx)\n* **Backend API**: `http://localhost:8080/`\n* **Qdrant DB Console**: `http://localhost:6333/dashboard`\n\n---\n\n## Security \u0026 Authentication Architecture\n\nThis project is built with a production-ready **Zero-Trust Security Design**:\n* **JSON Web Tokens (JWT)**: Secure endpoint boundaries are enforced for chat (`/api/chat/**`), ingestion (`/api/documents/**`), and writer (`/api/writer/**`).\n* **Sleek Client Auth Layer**: Establishes silent background session validation when the app mounts, saving JWTs in `localStorage` and injecting standard `Authorization: Bearer \u003ctoken\u003e` headers into every call.\n* **Cross-Platform Path Traversal Protection**: Implements robust directory anchoring and path normalization checks in Spring Boot controllers to ensure malicious players cannot retrieve system-level files using relative backslash attacks.\n* **Production Reverse Proxying**: Routes React assets and API endpoints seamlessly through Nginx, bypassing raw browser CORS locks on public environments.\n\n---\n\n## Repository Structure\n\n```text\nrag-assistant/\n├── backend/            # Spring Boot 3 Java Service\n│   ├── src/            # Parsing, chunking, security, and Spring AI logic\n│   ├── pom.xml         # Maven dependencies (Optimized: No H2 dependency)\n│   └── .env.example    # Backend environment template\n├── frontend/           # React 18 + Vite Web Application\n│   ├── src/            # Login, ChatWindow, and FileHub components\n│   ├── nginx.conf      # SPA routing \u0026 API reverse proxy configuration\n│   └── package.json    # Node scripts and dependencies\n├── uploads/            # Local carved image volumes (gitignored)\n├── qdrant_data/        # Persistent database storage (gitignored)\n├── .env.example        # Root environment variable templates\n└── docker-compose.yml  # Docker multi-container orchestrator\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoozuuu%2Frag-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoozuuu%2Frag-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoozuuu%2Frag-assistant/lists"}