# sghangs/insurancevirtualagent architecture

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

- Interactive diagram: https://gitdiagram.com/sghangs/insurancevirtualagent
- Repository: https://github.com/sghangs/insurancevirtualagent

## Overview

##### Project type and purpose
- This is a full-stack, cloud-native RAG (Retrieval-Augmented Generation) chatbot called “Insurance Virtual Agent.”
- Purpose: Ingest PDF policy documents into a vector store via AWS Lambda, then answer user queries by retrieving and augmenting policy data with OpenAI LLMs, all exposed through a lightweight frontend and API.

##### File structure
- Top-level service folders:
- LambdaSetup – code, Dockerfile, and requirements for the S3-triggered Lambda that tokenizes PDFs and pushes embeddings to Pinecone.
- backend – FastAPI (main.py) and Dockerfile exposing the RAG inference API (self-RAG agent).
- frontend – Streamlit app (app.py) packaged in its own Dockerfile for user interaction.
- evaluation – scripts and components to generate synthetic data and run automated model evaluations.
- src – core library modules (entity definitions, pipeline orchestration, retriever, prompts, logging, utilities).
- Configuration/deployment:
- docker-compose.yml for local integration of frontend, backend, and possibly a local vector DB stub.
- .github/workflows/deploy.yml for CI/CD.
- Data and logs:
- .vector_db – sample vector store snapshots.
- logs/ and src/logs – runtime logs for each component.

##### README for additional insights
- Architectural description: S3 → S3-notify → AWS Lambda ingestion → Pinecone vector index → API retrieval → LLM (gpt-4o) → user.
- Tech stack callouts: Python, AWS S3, Lambda, ECR, Pinecone, LangChain, LangGraph, OpenAI GPT-4, Streamlit, FastAPI, Docker, AWS EC2.

##### Detail without overcomplication
- Essential components listed above
- Configuration/deployment artifacts (Dockerfiles, GitHub Actions) as annotations or a separate “DevOps” lane
- Metadata filtering, hybrid search, and agentic RAG as callouts on the retrieval path

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        S3["Policy S3 Bucket"]:::aws
        Lambda["Embedding Lambda"]:::aws
        Pinecone["Pinecone Vector DB"]:::external
    end
    S3 -->|"S3 Notification"| Lambda
    Lambda -->|"Ingest Embeddings"| Pinecone

    %% Query Pipeline
    subgraph "Query Pipeline"
        User["User"]:::user
        Frontend["Streamlit UI"]:::service
        Backend["FastAPI RAG Service"]:::service
        OpenAI["OpenAI GPT-4 API"]:::external
    end
    User -->|"Query"| Frontend
    Frontend -->|"HTTP Request"| Backend
    Backend -->|"Vector Query"| Pinecone
    Backend -->|"LLM Call"| OpenAI
    OpenAI -->|"Response"| Backend
    Backend -->|"Answer"| Frontend
    Frontend -->|"Display"| User

    %% Core Library Modules
    subgraph "Core Library (src/)"
        SRC["src/"]:::service
        Retriever["Retriever Component"]:::service
        Pipeline["RAG Pipeline Orchestration"]:::service
        WorkflowGraph["Workflow Graph Definition"]:::service
        Prompts["Prompt Templates & Graders"]:::service
        LLMLayer["LLM Integration Layer"]:::service
        Entities["Entity Definitions"]:::service
        LogInfra["Logging Infrastructure"]:::service
        Utils["Utility Functions"]:::service
    end

    %% Data & Logs
    subgraph "Data & Logs"
        LocalSnapshot["Local Vector Store (.vector_db)"]:::data
        DataImages["Architecture Diagrams (data/Images)"]:::data
        Logs["Logs (src/logs/)"]:::data
    end

    %% DevOps
    subgraph "DevOps & Deployment"
        CICD["GitHub Actions CI/CD"]:::devops
        ECR["AWS ECR / EC2 Deployment"]:::aws
        Compose["docker-compose.yml"]:::devops
    end
    CICD -->|"Build & Push"| ECR
    Compose -.->|"Local Integration"| Frontend
    Compose -.->|"Local Integration"| Backend
    Compose -.->|"Local Vector DB Stub"| LocalSnapshot

    %% Evaluation
    subgraph "Evaluation & Synthetic Data"
        Eval["Evaluation & Synthetic Data"]:::service
        Synth["Synthesizer"]:::service
    end
    Eval --> Synth

    %% Click Events
    click Lambda "https://github.com/sghangs/insurancevirtualagent/blob/main/LambdaSetup/lambda_function.py"
    click Frontend "https://github.com/sghangs/insurancevirtualagent/blob/main/frontend/app.py"
    click Backend "https://github.com/sghangs/insurancevirtualagent/blob/main/backend/main.py"
    click LocalSnapshot "https://github.com/sghangs/insurancevirtualagent/tree/main/.vector_db/"
    click SRC "https://github.com/sghangs/insurancevirtualagent/tree/main/src/"
    click Retriever "https://github.com/sghangs/insurancevirtualagent/blob/main/src/retriever/retriever.py"
    click Pipeline "https://github.com/sghangs/insurancevirtualagent/blob/main/src/pipeline/rag.py"
    click WorkflowGraph "https://github.com/sghangs/insurancevirtualagent/blob/main/src/workflow/graph.py"
    click Prompts "https://github.com/sghangs/insurancevirtualagent/blob/main/src/prompts/prompts.py"
    click Prompts "https://github.com/sghangs/insurancevirtualagent/blob/main/src/prompts/graders.py"
    click LLMLayer "https://github.com/sghangs/insurancevirtualagent/tree/main/src/llm/"
    click Entities "https://github.com/sghangs/insurancevirtualagent/blob/main/src/entity/schema_entity.py"
    click LogInfra "https://github.com/sghangs/insurancevirtualagent/blob/main/src/loggers/logger.py"
    click Logs "https://github.com/sghangs/insurancevirtualagent/tree/main/src/logs/"
    click Utils "https://github.com/sghangs/insurancevirtualagent/blob/main/src/utility/utils.py"
    click CICD "https://github.com/sghangs/insurancevirtualagent/blob/main/.github/workflows/deploy.yml"
    click Compose "https://github.com/sghangs/insurancevirtualagent/blob/main/docker-compose.yml"
    click Evaluation "https://github.com/sghangs/insurancevirtualagent/blob/main/evaluation/evaluate.py"
    click Eval "https://github.com/sghangs/insurancevirtualagent/blob/main/evaluation/run_evaluation.py"
    click Synth "https://github.com/sghangs/insurancevirtualagent/blob/main/evaluation/deepeval_components/synthesizer.py"
    click Eval "https://github.com/sghangs/insurancevirtualagent/blob/main/scripts/generate_goldens.py"
    click DataImages "https://github.com/sghangs/insurancevirtualagent/tree/main/data/Images/"

    %% Styles
    classDef aws fill:#FF9900,stroke:#333,stroke-width:2px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:2px
    classDef service fill:#00CCFF,stroke:#333,stroke-width:2px
    classDef devops fill:#99FF66,stroke:#333,stroke-width:2px
    classDef data fill:#FFCC99,stroke:#333,stroke-width:2px
    classDef user fill:#FF6699,stroke:#333,stroke-width:2px
```
