# alisoliman/insurance-multi-agent architecture

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

- Interactive diagram: https://gitdiagram.com/alisoliman/insurance-multi-agent
- Repository: https://github.com/alisoliman/insurance-multi-agent

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-agent AI claims demo.
- Frontend: Next.js 15 (React 19) with shadcn/ui for interactive UIs and live agent dashboards.
- Backend: FastAPI (Python 3.12) orchestrating a LangGraph multi-agent workflow backed by Azure OpenAI (GPT-4.1) and FAISS vector search.
- Purpose: Accept insurance claims (text + PDFs + images), run them through specialized AI agents (Claim Assessor, Policy Checker, Risk Analyst, Communication Agent) under a Supervisor Agent, and present an explainable recommendation to the user.

##### File Structure
- Top-level directories:
– backend/: FastAPI app, endpoints (app/api/v1/endpoints), core config, models, services, workflow (agents, tools, supervisor).
– frontend/: Next.js app router (app/agents, app/documents, demo), global components, UI library (components/ui), API clients (lib).
– infra/: Azure Bicep templates for Container App environment, registry, roles.
– Dockerfiles for both frontend and backend, and azure.yaml for CI/CD.
- Architectural patterns:
– MVC-style separation in backend (endpoints ← services ← models).
– Supervisor pattern in LangGraph for orchestrating parallel agents.
– Infrastructure as code (IaC) with Bicep.

##### Extract Key Insights from README
- Multi-Agent Workflow: Supervisor dispatches Claim Assessor, Policy Checker, Risk Analyst in parallel; optionally triggers Communication Agent; returns synthesized summary.
- AI Providers: Azure OpenAI for LLM and embeddings; FAISS for local vector DB (planned Azure AI Search).
- Deployment: Azure Container Apps hosting two containers (frontend & backend) behind managed identities, ACR, Log Analytics, HTTPS endpoints.

##### Diagramming Conventions
– Blue rectangles for UI and frontend;
– Green for backend services and orchestration;
– Orange/Yellow for AI calls and vector DB;

##### Detailed Capture of Architectural Elements
- Explicitly show all five agents and PDF/policy tools.
- Vector store separately from raw policy files.
- Build pipeline (Dockerfiles + azure.yaml + Bicep) in a side note or as a CI/CD component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    Browser["User’s Browser"]:::ui

    subgraph "Frontend Container (Next.js)" 
        direction TB
        FE_APP["Next.js App"]:::ui
        subgraph "Agent Dashboards"
            direction TB
            CA_UI["Claim Assessor UI"]:::ui
            PC_UI["Policy Checker UI"]:::ui
            RA_UI["Risk Analyst UI"]:::ui
            COMM_UI["Communication Agent UI"]:::ui
        end
        subgraph "Demo & Documents"
            direction TB
            DEMO["Demo Scenarios Page"]:::ui
            DOC_INDEX["Document Index Management"]:::ui
            DOC_MANAGE["Document Upload/Manage"]:::ui
        end
        subgraph "Shared Components & API Clients"
            direction TB
            SHARED["Global Components"]:::ui
            SHADCN["shadcn/ui Components"]:::ui
            API_TS["API Clients & Utils"]:::ui
        end
    end

    %% Backend Layer
    subgraph "Backend Container (FastAPI)" 
        direction TB
        MAIN["main.py (Entry Point)"]:::backend
        subgraph "API Endpoints (Controllers)"
            direction TB
            WF_EP["workflow.py"]:::backend
            AG_EP["agent.py"]:::backend
            DOC_EP["documents.py / files.py"]:::backend
            IDX_EP["index_management.py"]:::backend
        end
        subgraph "Core & Config"
            direction TB
            CONFIG["config.py"]:::backend
            LOG_CFG["logging_config.py"]:::backend
        end
        subgraph "Services (Business Logic)"
            direction TB
            CLAIM_SVC["claim_processing.py"]:::backend
            AG_INVOC["single_agent.py"]:::backend
        end
        subgraph "Workflow Orchestrator"
            direction TB
            SUPERVISOR["supervisor.py"]:::backend
            subgraph "Agents (Parallel)"
                direction TB
                CLAIM_AG["claim_assessor.py"]:::backend
                POLICY_AG["policy_checker.py"]:::backend
                RISK_AG["risk_analyst.py"]:::backend
                COMM_AG["communication_agent.py"]:::backend
            end
            subgraph "Tools"
                direction TB
                PDF_PROC["pdf_processor.py"]:::backend
                POLICY_SRCH["policy_search.py"]:::backend
            end
            REG["registry.py"]:::backend
            TOOLS["tools.py"]:::backend
        end
        subgraph "Vector Store Data"
            direction TB
            POL_POL["policies/*.md"]:::ai
            INDEX_PKL["policy_index/index.pkl"]:::ai
            IDX_SCRIPT["build_policy_index.py"]:::ai
        end
    end

    %% External AI & Data Services
    subgraph "External AI & Data"
        direction TB
        AZ_OPENAI["Azure OpenAI Endpoint"]:::ai
        FAISS["FAISS Vector Store"]:::ai
    end

    %% Infra Layer
    subgraph "Infrastructure as Code & CI/CD"
        direction TB
        A_BICEP["main.bicep"]:::infra
        MOD_CA["container-apps-stack & containerapp.bicep"]:::infra
        MOD_ENV["environment.bicep"]:::infra
        MOD_ROLE["role-assignment.bicep"]:::infra
        CI_CD["azure.yaml"]:::infra
    end

    %% Connections
    Browser -->|"HTTP/HTTPS"| FE_APP
    FE_APP -->|"REST API"| MAIN
    MAIN -->|"orchestrates"| SUPERVISOR
    SUPERVISOR -->|parallel calls| CLAIM_AG
    SUPERVISOR -->|parallel calls| POLICY_AG
    SUPERVISOR -->|parallel calls| RISK_AG
    SUPERVISOR -->|conditional| COMM_AG
    CLAIM_AG -->|"LLM calls"| AZ_OPENAI
    POLICY_AG -->|"LLM calls"| AZ_OPENAI
    RISK_AG -->|"LLM calls"| AZ_OPENAI
    COMM_AG -->|"LLM calls"| AZ_OPENAI
    POLICY_SRCH -->|"semantic search"| FAISS
    PDF_PROC -->|"extract text"| MAIN
    SUPERVISOR -->|returns summary| MAIN
    MAIN -->|"JSON response"| FE_APP
    FE_APP -->|"renders dashboards"| Browser
    A_BICEP -->|deploy| FE_APP
    A_BICEP -->|deploy| MAIN
    FE_APP -->|logs| CI_CD
    MAIN -->|logs| CI_CD

    %% Click Events
    click FE_APP "https://github.com/alisoliman/insurance-multi-agent/tree/main/frontend/"
    click CA_UI "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/app/agents/claim-assessor/page.tsx"
    click PC_UI "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/app/agents/policy-checker/page.tsx"
    click RA_UI "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/app/agents/risk-analyst/page.tsx"
    click COMM_UI "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/app/agents/communication-agent/page.tsx"
    click DEMO "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/app/demo/page.tsx"
    click DOC_INDEX "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/app/documents/index-management/page.tsx"
    click DOC_MANAGE "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/app/documents/manage/page.tsx"
    click SHARED "https://github.com/alisoliman/insurance-multi-agent/tree/main/frontend/components/"
    click SHADCN "https://github.com/alisoliman/insurance-multi-agent/tree/main/frontend/components/ui/"
    click API_TS "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/lib/api.ts"
    click API_TS "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/lib/dashboard-api.ts"
    click API_TS "https://github.com/alisoliman/insurance-multi-agent/blob/main/frontend/lib/utils.ts"
    click MAIN "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/main.py"
    click WF_EP "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/api/v1/endpoints/workflow.py"
    click AG_EP "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/api/v1/endpoints/agent.py"
    click DOC_EP "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/api/v1/endpoints/documents.py"
    click DOC_EP "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/api/v1/endpoints/files.py"
    click IDX_EP "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/api/v1/endpoints/index_management.py"
    click CONFIG "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/core/config.py"
    click LOG_CFG "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/core/logging_config.py"
    click CLAIM_SVC "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/services/claim_processing.py"
    click AG_INVOC "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/services/single_agent.py"
    click SUPERVISOR "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/supervisor.py"
    click CLAIM_AG "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/agents/claim_assessor.py"
    click POLICY_AG "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/agents/policy_checker.py"
    click RISK_AG "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/agents/risk_analyst.py"
    click COMM_AG "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/agents/communication_agent.py"
    click PDF_PROC "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/pdf_processor.py"
    click POLICY_SRCH "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/policy_search.py"
    click REG "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/registry.py"
    click TOOLS "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/tools.py"
    click POL_POL "https://github.com/alisoliman/insurance-multi-agent/tree/main/backend/app/workflow/data/policies/"
    click INDEX_PKL "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/app/workflow/data/policy_index/index.pkl"
    click IDX_SCRIPT "https://github.com/alisoliman/insurance-multi-agent/blob/main/backend/build_policy_index.py"
    click A_BICEP "https://github.com/alisoliman/insurance-multi-agent/blob/main/infra/main.bicep"
    click MOD_CA "https://github.com/alisoliman/insurance-multi-agent/blob/main/infra/modules/container-apps-stack.bicep"
    click MOD_CA "https://github.com/alisoliman/insurance-multi-agent/blob/main/infra/modules/containerapp.bicep"
    click MOD_ENV "https://github.com/alisoliman/insurance-multi-agent/blob/main/infra/modules/environment.bicep"
    click MOD_ROLE "https://github.com/alisoliman/insurance-multi-agent/blob/main/infra/modules/role-assignment.bicep"
    click CI_CD "https://github.com/alisoliman/insurance-multi-agent/blob/main/azure.yaml"

    %% Styles
    classDef ui fill:#D3E5FF,stroke:#1E88E5,stroke-width:1px;
    classDef backend fill:#D8F5D3,stroke:#43A047,stroke-width:1px;
    classDef ai fill:#FFF3CD,stroke:#FB8C00,stroke-width:1px;
    classDef infra fill:#E0E0E0,stroke:#616161,stroke-width:1px;
```
