# abhishekn1947/vertex-ai-pdf-bot architecture

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

- Interactive diagram: https://gitdiagram.com/abhishekn1947/vertex-ai-pdf-bot
- Repository: https://github.com/abhishekn1947/vertex-ai-pdf-bot

## Overview

##### Project type and purpose
- This is a lightweight, full-stack web application built with Streamlit.
- Purpose: Let end users upload large PDF files (up to 200 MB), locally process them into embeddings and indexes, then ask free-form questions answered by a combination of local retrieval and Google Cloud Vertex AI LLM calls.

##### File structure
- Top-level files:
- main.py (Streamlit app, contains both “frontend” UI code and “backend” data-processing logic)
- requirements.txt (Python dependencies, including streamlit, langchain, chromadb, google-cloud-aiplatform)
- README.md / LICENSE
- No separate “frontend” or “backend” folders—everything runs in one monolithic Streamlit process.
- No dedicated config folder; environment variables (GOOGLE_APPLICATION_CREDENTIALS, project_id, location) are set externally.

##### Key architectural insights from the README
- Frontend: Streamlit UI for file upload and chat interaction.
- Document ingestion pipeline:
1) PDF loader
2) Text splitter / chunker
3) Embedding generator (via Vertex AI Embeddings)
4) Vector store (ChromaDB by default)
- Query pipeline:
1) Retrieve relevant chunks from vector store
2) Send prompt + context to Vertex AI LLM (e.g., PaLM 2)
3) Return answer to UI
- Optional: User can push data to their own BigQuery, ensuring data privacy/external storage.

##### Main components
a. Client (Web Browser)
b. Streamlit Server (main.py)
- UI Module: file-upload widget, question input, results display
- Ingestion Module: PDF Loader → Text Splitter → Embedding Client → Vector Store
- Query Module: Vector Store → Retrieval → LLM Client → Response Formatter
c. Local Persistence
- Chroma Vector Store (local on disk)
- Optional BigQuery Dataset (user-managed)
d. External Services
- Google Cloud Vertex AI Embeddings API
- Google Cloud Vertex AI LLM API
e. Environment Configuration
- GOOGLE_APPLICATION_CREDENTIALS (service account JSON)
- GCP project_id & location

##### Relationships & interactions
- User → Streamlit UI (upload PDF, ask question)
- UI triggers Ingestion Module → writes embeddings to Vector Store
- Query: Retrieval Module pulls nearest vectors → LLM Client calls Vertex AI → returns generated text
- All network calls to GCP services happen over secure HTTPS

##### Architectural patterns & design principles
- Monolithic single-process application (Streamlit)
- Pipeline pattern for ingestion & query (loader → splitter → embed → store / retrieve → LLM)
- Separation of concerns: UI vs. data pipeline vs. external API client
- Pluggable storage (local Chroma vs. BigQuery)
- Externalize credentials/config via environment variables

##### Essential details to capture
- Modules inside main.py (UI vs. ingestion vs. query)
- Environment/config layer
- Local vs. external storage distinction
- Upstream flow (PDF ingestion) vs. downstream flow (user Q&A)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client / Presentation"
        Browser["Web Browser"]:::client
        UI["Streamlit UI Module"]:::processing
    end

    subgraph "Backend / Processing"
        subgraph "Ingestion Module"
            PDF["PDF Loader"]:::processing
            Split["Text Splitter / Chunker"]:::processing
            Embed["Embedding Generator"]:::processing
            Store["Vector Store Integration"]:::processing
        end
        subgraph "Query Module"
            Retrieve["Retrieval Logic"]:::processing
            LLMClient["LLM Client"]:::processing
            Format["Response Formatter"]:::processing
        end
    end

    subgraph "Storage"
        Chroma["ChromaDB Vector Store"]:::storage
        BigQuery["BigQuery (Optional)"]:::storage
    end

    subgraph "External Services"
        Embeddings["Vertex AI Embeddings"]:::external
        LLM["Vertex AI LLM"]:::external
    end

    subgraph "Environment & Docs"
        Env["Environment Variables"]:::config
        Req["requirements.txt"]:::doc
        Readme["README.md"]:::doc
        License["LICENSE"]:::doc
    end

    %% Data flows
    Browser -->|"upload PDF / ask question"| UI
    UI -->|"trigger ingestion"| PDF
    PDF -->|"loaded text"| Split
    Split -->|"text chunks"| Embed
    Embed -->|"getEmbeddings()"| Embeddings
    Embed -->|"storeEmbeddings()"| Chroma
    Store --> Chroma

    UI -->|"question query"| Retrieve
    Retrieve -->|"searchVectors()"| Chroma
    Retrieve -->|"optional push"| BigQuery
    Retrieve -->|"context + prompt"| LLMClient
    LLMClient -->|"generateText()"| LLM
    LLMClient --> Format
    Format --> UI

    %% Config & Docs access (annotations)
    Env --- UI
    Req --- UI
    Readme --- UI
    License --- UI

    %% Click Events
    click UI "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/main.py"
    click PDF "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/main.py"
    click Split "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/main.py"
    click Embed "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/main.py"
    click Store "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/main.py"
    click Retrieve "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/main.py"
    click LLMClient "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/main.py"
    click Format "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/main.py"
    click Req "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/requirements.txt"
    click Readme "https://github.com/abhishekn1947/vertex-ai-pdf-bot/blob/main/README.md"
    click License "https://github.com/abhishekn1947/vertex-ai-pdf-bot/tree/main/LICENSE"

    %% Styles
    classDef client fill:#D0E7FF,stroke:#0066CC,color:#003366;
    classDef processing fill:#E8F4FF,stroke:#3399FF,color:#0059b3;
    classDef storage fill:#DFFFE0,stroke:#33CC33,color:#007700;
    classDef external fill:#FFE5B4,stroke:#FF9900,color:#CC6600;
    classDef config fill:#F0F0F0,stroke:#999999,color:#666666;
    classDef doc fill:#F9F9F9,stroke:#CCCCCC,color:#999999;
```
