# debnsuma/genai-insurance-automation architecture

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

- Interactive diagram: https://gitdiagram.com/debnsuma/genai-insurance-automation
- Repository: https://github.com/debnsuma/genai-insurance-automation

## Overview

##### Project Type and Purpose
- This repository is an end-to-end generative-AI solution for two insurance use cases:
- Part 1: A Jupyter/Python ML pipeline that uses Amazon Bedrock’s Claude model to generate data-processing and model-training code for insurance renewal prediction.
- Part 2: A serverless, agent-driven insurance-claim automation system that leverages Amazon Bedrock Agents, AWS Lambda, S3-backed knowledge bases, and RAG to orchestrate multi-step tasks (create claim, gather evidence, send reminders).

##### File Structure
- Part1-Code Generation/
- data_ml.csv, ML notebooks, model_code.py, src/claude_llm_invocation.py – a standalone ML pipeline and code-generation client for Bedrock.
- Part2-Insurance Claim Lifecycle/
- agent/ – OpenAPI schema JSON, Lambda functions (action-groups), Streamlit UI, lambda layers.
- cfn/ – CloudFormation YAML to provision Bedrock agents, knowledge bases, roles.
- documentation/ – deployment guide, testing, cleanup.
- shell/ – Bash scripts to create/delete AWS resources.

##### README for Architectural Insights
- It describes a six-step Bedrock-Agents workflow: user input → pre-processing → action-groups (API) → knowledge-base queries → orchestration (ReAct loops) → post-processing.
- Key AWS services: Amazon Bedrock, S3 (schemas, data, docs), AWS Lambda, Lambda Layers, CloudFormation, Python (Streamlit, Boto3).

##### Main Components
a. Frontend Interfaces
- Jupyter notebooks & ML scripts (Part 1)
- Streamlit application (Part 2)
b. Core Bedrock Agent Orchestrator
- Amazon Bedrock runtime with foundation models (Claude, embedding models)
- Agent logic (pre-/post-processing, ReAct prompt engine)
c. Action Groups Layer
- JSON OpenAPI schemas in S3
- AWS Lambda functions implementing create_claim, gather_evidence, send_reminder
- Lambda Layers (common code, Bedrock SDK)
d. Knowledge Base Layer
- S3 data source (policy docs, claims evidence)
- Vector store embeddings managed by Bedrock KB
- RAG retrieval APIs
e. Infrastructure Provisioning
- CloudFormation stack for Agents, KB, Roles
- Shell scripts to bootstrap or tear down resources

##### Relationships and Data Flow
1. User interacts via Streamlit or notebooks → sends natural-language prompt or ML code request.
2. Frontend invokes Bedrock Agent API (via Boto3).
3. Agent preprocesses the task, consults chat history and instructions.
4. Agent queries S3-hosted OpenAPI schemas to discover which Lambda to call.
5. Agent invokes the appropriate AWS Lambda (action group) to run business logic or load data.
6. For knowledge queries, Agent calls Bedrock KB retrieval endpoints (RAG) against S3 data.
7. Agent orchestrates ReAct loops: alternating FM calls and action-group/KB calls until the task is complete.
8. Final response is returned to the user interface.
9. Part 1 ML pipeline: Notebook calls claude_llm_invocation.py → requests code templates from Claude → trains scikit-learn model locally.

##### Architectural Patterns and Principles
- Serverless Micro-services: each action group is a Lambda function with its own OpenAPI schema.
- ReAct Orchestration: separates reasoning (LLM) from action execution (Lambda/APIs).
- RAG (Retrieval-Augmented Generation): embeds and retrieves domain documents via Bedrock KB.
- Infrastructure as Code: CloudFormation + shell scripts manage provisioning and cleanup.
- Separation of Concerns: distinct layers for UI, orchestration, action execution, and data management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Part 1: ML Code-Generation Pipeline
    subgraph "Part 1: ML Code-Gen Pipeline"
        direction TB
        JN1["LIVE-insurance_renewal_prediction.ipynb"]:::frontend
        JN2["insurance_renewal_prediction.ipynb"]:::frontend
        DataCSV1["data_ml.csv"]:::data
        DataCSV2["data_ml_test.csv"]:::data
        ModelScript["model_code.py"]:::backend
        ClaudeClient["claude_llm_invocation.py"]:::backend
        JN1 -->|"reads/writes"| DataCSV1
        JN2 -->|"reads/writes"| DataCSV2
        JN1 -->|"calls"| ClaudeClient
        JN2 -->|"calls"| ClaudeClient
        ClaudeClient -->|"generates code"| ModelScript
    end

    %% Part 2: Insurance Claim Lifecycle Agent
    subgraph "Part 2: Serverless Agent Platform"
        direction TB
        StreamlitUI["Streamlit UI"]:::frontend
        Sigv4["sigv4.py"]:::backend
        SetupEnv["setup-streamlit-env.sh"]:::backend
        StreamlitUI -->|"imports"| Sigv4
        StreamlitUI -->|"runs"| SetupEnv

        %% Bedrock Agent Orchestrator
        subgraph "Agent Orchestrator (Amazon Bedrock)" 
            direction TB
            BedrockFX[(Bedrock Foundation Models)]:::cloud
            AgentLogic["Agent Logic (ReAct)"]:::cloud
            KBRetrieval["KB Retrieval API (RAG)"]:::cloud
        end
        StreamlitUI -->|"Boto3 call"| AgentLogic
        AgentLogic -->|"invokes FM"| BedrockFX
        AgentLogic -->|"retrieves"| KBRetrieval

        %% Action Groups
        subgraph "Action Groups Layer"
            direction TB
            OA1["create_claim.json"]:::doc
            OA2["gather_evidence.json"]:::doc
            OA3["send_reminder.json"]:::doc
            Lambda1["create_claim.py"]:::lambda
            Lambda2["gather_evidence.py"]:::lambda
            Lambda3["send_reminder.py"]:::lambda
            OA1 -->|"defines API"| Lambda1
            OA2 -->|"defines API"| Lambda2
            OA3 -->|"defines API"| Lambda3
            AgentLogic -->|"discovers"| OA1
            AgentLogic -->|"discovers"| OA2
            AgentLogic -->|"discovers"| OA3
            AgentLogic -->|"invokes"| Lambda1
            AgentLogic -->|"invokes"| Lambda2
            AgentLogic -->|"invokes"| Lambda3
        end

        %% Data Loader
        subgraph "Initial Data Loader"
            direction TB
            ClaimsData["claims.json"]:::data
            LoaderFunc["index.py"]:::lambda
            StreamLoader["loader_deployment_package.zip"]:::lambda
            ClaimsData -->|"loaded by"| LoaderFunc
            AgentLogic -->|"can invoke"| LoaderFunc
        end

        %% Lambda Layers
        subgraph "Lambda Layers"
            direction TB
            Layer1["bedrock-agents-layer.zip"]:::layer
            Layer2["cfnresponse-layer.zip"]:::layer
        end
        Lambda1 --> Layer1
        Lambda2 --> Layer1
        Lambda3 --> Layer1
        LoaderFunc --> Layer2

        %% Knowledge Base Assets
        KBData["S3 RAG Documents"]:::data
        KBData --> KBRetrieval

    end

    %% Infrastructure Provisioning
    subgraph "Infrastructure as Code"
        direction TB
        CFN["bedrock-customer-resources.yml"]:::infra
        ScriptCreate["create-customer-resources.sh"]:::infra
        ScriptDelete["delete-customer-resources.sh"]:::infra
        CFN --> ScriptCreate
        CFN --> ScriptDelete
    end

    %% Project Documentation
    subgraph "Documentation"
        direction TB
        Doc1["deployment-guide.md"]:::doc
        Doc2["testing-and-validation.md"]:::doc
        Doc3["clean-up.md"]:::doc
    end

    %% Click Events
    click JN1 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part1-Code Generation/LIVE-insurance_renewal_prediction.ipynb"
    click JN2 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part1-Code Generation/insurance_renewal_prediction.ipynb"
    click DataCSV1 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part1-Code Generation/data_ml.csv"
    click DataCSV2 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part1-Code Generation/data_ml_test.csv"
    click ModelScript "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part1-Code Generation/model_code.py"
    click ClaudeClient "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part1-Code Generation/src/claude_llm_invocation.py"
    click StreamlitUI "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/streamlit/bedrock_streamlit.py"
    click SetupEnv "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/streamlit/setup-streamlit-env.sh"
    click Sigv4 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/streamlit/sigv4.py"
    click OA1 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/api-schema/create_claim.json"
    click OA2 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/api-schema/gather_evidence.json"
    click OA3 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/api-schema/send_reminder.json"
    click KBData "https://github.com/debnsuma/genai-insurance-automation/tree/main/Part2-Insurance Claim Lifecycle/agent/knowledge-base-assets/"
    click Lambda1 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/lambda/action-groups/create_claim.py"
    click Lambda2 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/lambda/action-groups/gather_evidence.py"
    click Lambda3 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/lambda/action-groups/send_reminder.py"
    click ClaimsData "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/lambda/data-loader/claims.json"
    click LoaderFunc "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/lambda/data-loader/index.py"
    click Layer1 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/lambda/lambda-layer/bedrock-agents-layer.zip"
    click Layer2 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/agent/lambda/lambda-layer/cfnresponse-layer.zip"
    click CFN "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/cfn/bedrock-customer-resources.yml"
    click ScriptCreate "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/shell/create-customer-resources.sh"
    click ScriptDelete "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/shell/delete-customer-resources.sh"
    click Doc1 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/documentation/deployment-guide.md"
    click Doc2 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/documentation/testing-and-validation.md"
    click Doc3 "https://github.com/debnsuma/genai-insurance-automation/blob/main/Part2-Insurance Claim Lifecycle/documentation/clean-up.md"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#e2e3e5,stroke:#b8b9ba,color:#383d41
    classDef cloud fill:#ffeeba,stroke:#856404,color:#856404
    classDef lambda fill:#d4edda,stroke:#155724,color:#155724
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef doc fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef layer fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef infra fill:#fdfdfe,stroke:#6c757d,color:#6c757d
```
