# alonlavian/ragent architecture

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

- Interactive diagram: https://gitdiagram.com/alonlavian/ragent
- Repository: https://github.com/alonlavian/ragent

## Overview

##### Project Type and Purpose
- The project is an AI-powered research assistant that allows users to upload PDFs, query AI models, and retrieve enhanced information through integrated web search.
- It uses Streamlit as the frontend, while the backend handles document processing, vector database operations, and API integrations (for services like Claude and Tavily web search).

##### Main Components
a. Frontend Interface:
– Represent the Streamlit user interface (streamlit_app.py) as the entry point.
– Indicate that it provides functionalities like toggling Dry Run Mode (via a checkbox) and uploading PDFs.

b. Backend Core:
– Include an “Application Logic” module (app.py) that coordinates overall query handling and PDF processing.
– A “Utilities Module” (utils.py) for various processing tasks and common functions.
– A “Vector Database Module” (vector_db.py) dedicated to interactions with the vector store and related data operations.

c. External Integrations:
– External API integrations for:
▪ AI Response Handling (e.g., call_claude_rag for getting AI-powered responses).
▪ Web Search Enhancements (e.g., call_tavily_web_search to integrate search results).
▪ Additional steps like assess_confidence and synthesize_information for refining the provided responses.
– The Dry Run functionality that propagates a “dry_run” flag to these components and forces them to return mock data instead of live results.

##### Relationships and Data Flows
- From the UI, user actions (like PDF upload or query submission) trigger backend operations in app.py.
- In the backend:
– The PDF processing element sends documents to the Vector Database component (managed by vector_db.py) to build or query a vector store.
– API calls are made depending on the query, flowing into external services (both the Claude API for AI responses and the Tavily web search for additional results).
– Throughout these operations, the “dry_run” flag is checked, and if active, the calls are replaced by mock responses.
- The processed and aggregated data is then sent back to the UI for display.

##### Architectural Patterns and Principles
- The system follows a modular design:
– Clear separation between the UI and backend logic.
– Dedicated components for external integrations.
- There is an emphasis on extensibility with explicit “Dry Run Mode” to facilitate testing without side effects.
- The overall design is loosely coupled, which makes it easier to update individual functions or integrations without affecting the entire system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User Actions"]:::user
    A["Frontend (Streamlit Interface)"]:::frontend
    B["Application Logic (app.py)"]:::backend
    C["Utilities (utils.py)"]:::backend
    D["Vector Database (vector_db.py)"]:::backend
    DR["Dry Run Mode Active (Mock Data)"]:::note

    subgraph "External Integrations"
        E["Claude API"]:::external
        F["Tavily Web Search"]:::external
        G["Assess Confidence"]:::external
        H["Synthesize Information"]:::external
    end

    U -->|"uploads,queries"| A
    A -->|"triggers"| B
    B -->|"invokes"| C
    B -->|"processesPDFs"| D
    D -->|"returnsVectorData"| B
    B -->|"calls"| E
    B -->|"calls"| F
    B -->|"calls"| G
    B -->|"calls"| H
    B -->|"aggregatesResults"| A
    B ---|"propagatesDryRunFlag"| DR

    click A "https://github.com/alonlavian/ragent/blob/main/streamlit_app.py"
    click B "https://github.com/alonlavian/ragent/blob/main/app.py"
    click C "https://github.com/alonlavian/ragent/blob/main/utils.py"
    click D "https://github.com/alonlavian/ragent/blob/main/vector_db.py"

    classDef user fill:#FFFACD,stroke:#000,stroke-width:1px;
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef note fill:#D3D3D3,stroke:#000,stroke-dasharray: 5 5,stroke-width:1px;
```
