System Requirements Document for Verdant-a

Introduction

Verdant-a is a production-grade, privacy-focused Document Q&A (RAG) web application designed to operate entirely locally, ensuring zero external API calls. This document outlines the system requirements for Verdant-a, focusing on its architecture, functional capabilities, user interactions, and design elements.

System Overview

Verdant-a is a web application that allows users to upload documents and ask questions about their content. The system processes documents locally, generates embeddings, and retrieves relevant information using a local LLM, all while maintaining user privacy by avoiding external API calls.

Source Content Inventory

• Frontend: Next.js (React), TypeScript, Tailwind CSS, Shadcn UI
• Backend: FastAPI (Python 3.11)
• Local LLM & Embedding Runner: Ollama or LocalAI via Docker
  • LLM Model: mistral:7b-instruct or llama3:8b-instruct
  • Embedding Model: BAAI/bge-small-en-v1.5 or all-minilm-L6-v2
• Vector Database: Qdrant or ChromaDB
• Orchestration Framework: LangChain or LlamaIndex
• PDF Parser: PyMuPDF (fitz) or pypdf

Functional Requirements as Story Points

• As a User, I should be able to upload a PDF via a drag-and-drop web UI.
• As a User, I should see real-time upload progress and parsing status.
• As a User, I should be able to ask questions in the chat interface.
• As a User, I should receive answers with source citations showing page numbers and text snippets.
• As a User, I should have my queries converted to embeddings locally for privacy.
• As a User, I should have my queries processed with a local LLM using a tailored RAG prompt template.
• As a User, I should see answers streamed back to the UI in real-time.
• As a Developer, I should have a fallback script to download models during the initial Docker build.
• As a Developer, I should have automated tests for PDF parsing, embedding generation, and vector retrieval.
• As a Developer, I should have autogenerated OpenAPI documentation for API endpoints.

User Personas

• End User: Individuals who upload documents and interact with the Q&A system.
• Developer: Engineers responsible for maintaining and improving the system.
• Administrator: Personnel managing the infrastructure and ensuring system security.

Core User Flows

• User uploads a PDF -> System parses and chunks the document -> Embeddings are generated and stored -> User asks a question -> System retrieves relevant chunks -> LLM processes the query -> Answer is streamed back with source citations.

Visuals Colors and Theme

• primary: #1E3A8A (Deep Indigo)
• primary_light: #3B82F6 (Light Blue)
• secondary: #F59E0B (Amber)
• accent: #EF4444 (Red)
• highlight: #FBBF24 (Gold)
• bg: #F3F4F6 (Light Gray)
• surface: rgba(255, 255, 255, 0.8)
• text: #111827 (Dark Gray)
• text_muted: #6B7280 (Muted Gray)
• border: rgba(209, 213, 219, 0.2)

Signature Design Concept

Interactive Document Journey

The homepage will feature an interactive document journey visualization. Users will see a digital document icon that, when hovered over, expands to show a flow of data being processed. This animation will illustrate the document being parsed, chunked, and analyzed, with visual cues like glowing lines and expanding nodes representing the data flow. Users can click on different stages to see detailed animations of each process, such as text extraction and embedding generation.

Landing Hero Motion Brief

The landing hero will depict a document icon transforming into a network of interconnected nodes, symbolizing data processing. As users scroll, the nodes will animate to show the flow of information through the system, culminating in a visual representation of the answer generation process. This will be achieved using motion/react for smooth transitions and interactive elements.

Interaction Model & Motion Direction

• Intended Interaction Model: Animated
  • The landing page will feature moderate scroll-triggered reveals and hover transitions.
  • Interactive elements will have spring physics for a polished user experience.
• Internal Pages: Static for clarity and minimal motion.

Non-Functional Requirements

• The system must operate entirely locally with no external API calls.
• All configurations should point to local endpoints.
• The application should support dark mode for user comfort.

Tech Stack

• Frontend: Next.js, TypeScript, Tailwind CSS, Shadcn UI
• Backend: FastAPI (Python 3.11)
• Local LLM & Embedding Runner: Ollama or LocalAI
• Vector Database: Qdrant or ChromaDB
• Orchestration Framework: LangChain or LlamaIndex
• PDF Parser: PyMuPDF or pypdf
• Containerization: Docker, Docker Compose

Assumptions and Constraints

• The application will run on local infrastructure with Docker.
• All models and databases will be containerized for easy deployment.
• The system must handle documents up to a specified size efficiently.

Glossary

• RAG: Retrieval-Augmented Generation
• LLM: Large Language Model
• Qdrant: A vector database for storing embeddings
• Ollama: A local inference engine for running LLMs
• LangChain: A framework for building applications with language models
• PDF Parser: Software for extracting text from PDF documents

This document outlines the comprehensive requirements for the Verdant-a project, ensuring a fully localized, privacy-focused application.