# maharun0/cse299 architecture

> Architecture diagram of the GitHub repository maharun0/cse299, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maharun0/cse299
- Repository: https://github.com/maharun0/cse299

## Overview

##### Project Type and Purpose
- This is a hybrid document retrieval and conversational AI system that combines offline (local document processing and vector-based search) with online retrieval capabilities. The system is designed for securely processing personal or specialized documents, indexing them locally using FAISS, and then engaging users in interactive, conversational searches with the help of adaptive AI models.

##### File Structure
- Key Directories & Files:
- BotUtils: Contains core modules such as Chain.py, Chunker.py, DocumentLoader.py, OllamaStuffs.py, Prompt.py, Reranker.py, and VectorStore.py. These likely support document ingestion, processing, vector indexing, query formulation, and reranking of results.
- server: Houses main backend scripts (server/main.py, server/terminal_bot.py) and the vector database storage (server/vector_db with FAISS indexes). It also includes sample documents (aida.pdf, physics_book.pdf) used as input files.
- frontend: Contains the UI entry point (frontend.py) and supporting files (images). This represents the chat interface.
- main.py at the project root appears to act as an orchestrator that ties together the frontend, backend, MongoDB sessions, and calls to Ollama (external AI service).
- Reports and Tests: Provide demonstrations, proposals, and test cases but aren’t central to runtime architecture.
- Architectural Patterns:
- The clear separation of frontend, backend, and utility modules points toward a modular, layered approach. The BotUtils modules encapsulate specific RAG pipeline stages (document loading, chunking, vector search, reranking), while the server code manages storage of indexed data and integration with external services.
- The use of both local vector databases (e.g., FAISS) and external AI resources (Ollama) highlights a hybrid retrieval model.

##### README for Additional Insights
- The README emphasizes that the project’s core is to provide hybrid retrieval combining local indexing (ensuring privacy) and online mode for accessing additional computational resources.
- Key features include efficient document processing, vector-based search, reranking, and adaptive AI models.
- There’s a visual reference to a RAG pipeline image in the README, suggesting that stages of retrieval augmentation should be clearly represented.

a. Main Components:
- Frontend: Chat UI (frontend/frontend.py) from which user queries originate.
- Backend/API: Runs via main.py and server/main.py, managing the conversation flow.
- RAG Pipeline Utilities: Core modules in BotUtils that perform document loading (DocumentLoader), text extraction and chunking (Chunker), prompt generation (Prompt), query chaining (Chain), vector storage handling (VectorStore), and reranking (Reranker). You may also mention Ollama-related functions from OllamaStuffs.
- Vector Database: Represented by FAISS indexes in server/vector_db.
- External Services: MongoDB (for session management) and Ollama (for AI model inference) as indicated in the README.
- File Storage: Documents located in server/files (PDFs, physics book) which are processed by the system.

b. Component Relationships and Data Flow:
- User Query Flow: User inputs are sent from the Frontend to the Backend.
- Request Processing: The Backend orchestrates the RAG Pipeline; it directs the document processing modules (document loading, chunking) to handle local files.
- Vector Search: The processed document text is transformed into embeddings via BotUtils/VectorStore, using FAISS for nearest neighbor search.
- Reranking: The Reranker refines the search results, potentially using further cross-encoder calls.
- Response Generation: Based on the hybrid retrieval (offline processed content combined with possible online/contextual lookups via Ollama), the final conversational response is formulated and returned to the Frontend.
- Data Storage and External Dependencies: MongoDB manages session data and possibly logging of queries; Ollama supplies model inference (as per the prerequisites noted in the README).

c. Important Architectural Patterns and Design Principles:
- Modularity: Each component of the RAG pipeline is compartmentalized (utility modules under BotUtils).
- Hybrid Retrieval: Clear separation between local (on-device, privacy-preserving) processing and online mode (external AI model inference).
- Responsiveness: The system is designed for interactive conversation, indicating asynchronous or real-time data flow between components.
- Security & Privacy: Emphasis on processing sensitive documents locally before invoking external resources.

d. Relevant Technologies & Frameworks:
- FAISS: Used for vector indexing and similarity search.
- MongoDB: Manages sessions and possibly stateful interactions.
- Ollama: External AI service provider for model inference.
- Python Modules: The use of Python scripts throughout; consider using libraries like Flask or similar frameworks if applicable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        ChatUI["Chat UI"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API_main["API Controller (main.py)"]:::backend
        API_server["API Controller (server/main.py)"]:::backend
        API_main --> API_server
    end

    %% RAG Pipeline
    subgraph "RAG Pipeline"
        DocumentLoader["DocumentLoader"]:::pipeline
        Chunker["Chunker"]:::pipeline
        Chain["Chain"]:::pipeline
        Prompt["Prompt"]:::pipeline
        VectorStore["VectorStore"]:::pipeline
        Reranker["Reranker"]:::pipeline
        OllamaStuffs["OllamaStuffs"]:::pipeline
    end

    %% Data Storage & External Systems
    subgraph "Data Storage & External Systems"
        FileStorage["Static File Storage"]:::storage
        VectorDatabase["Vector Database (FAISS)"]:::storage
        MongoDB["Database (MongoDB)"]:::external
    end

    %% Connections
    ChatUI -->|"sends query"| API_main
    API_server -->|"orchestrates"| DocumentLoader

    %% File ingestion branch
    FileStorage -->|"loads documents"| DocumentLoader

    %% RAG Pipeline flow
    DocumentLoader -->|"extracts text"| Chunker
    Chunker -->|"forms query context"| Chain
    Chain -->|"generates prompt"| Prompt
    Prompt -->|"embeds text"| VectorStore
    VectorStore -->|"queries for similarity"| VectorDatabase
    Chain -->|"calls for external inference"| OllamaStuffs
    VectorStore -->|"sends candidates"| Reranker
    OllamaStuffs -->|"sends inference"| Reranker

    %% Pipeline result back to API and then Frontend
    Reranker -->|"aggregates answer"| API_server
    API_server -->|"responds"| ChatUI

    %% API uses external session store
    API_server -->|"stores session"| MongoDB

    %% Click Events
    click ChatUI "https://github.com/maharun0/cse299/blob/main/frontend/frontend.py"
    click API_main "https://github.com/maharun0/cse299/blob/main/main.py"
    click API_server "https://github.com/maharun0/cse299/blob/main/server/main.py"
    click DocumentLoader "https://github.com/maharun0/cse299/blob/main/BotUtils/DocumentLoader.py"
    click Chunker "https://github.com/maharun0/cse299/blob/main/BotUtils/Chunker.py"
    click Chain "https://github.com/maharun0/cse299/blob/main/BotUtils/Chain.py"
    click Prompt "https://github.com/maharun0/cse299/blob/main/BotUtils/Prompt.py"
    click VectorStore "https://github.com/maharun0/cse299/blob/main/BotUtils/VectorStore.py"
    click Reranker "https://github.com/maharun0/cse299/blob/main/BotUtils/Reranker.py"
    click OllamaStuffs "https://github.com/maharun0/cse299/blob/main/BotUtils/OllamaStuffs.py"
    click FileStorage "https://github.com/maharun0/cse299/tree/main/server/files"
    click VectorDatabase "https://github.com/maharun0/cse299/tree/main/server/vector_db"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#C1F0C1,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#FFF2CC,stroke:#333,stroke-width:2px;
    classDef storage fill:#D5A6BD,stroke:#333,stroke-width:2px;
    classDef external fill:#F9CB9C,stroke:#333,stroke-width:2px;
```
