# aasawari-m10/health-insurance-policy-advisor architecture

> Architecture diagram of the GitHub repository aasawari-m10/health-insurance-policy-advisor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aasawari-m10/health-insurance-policy-advisor
- Repository: https://github.com/aasawari-m10/health-insurance-policy-advisor

## Overview

This repository implements a health-insurance policy advisor with a FastAPI interface and MCP tools. The main question workflow classifies intent, resolves a policy version, checks safety constraints, retrieves plan-scoped clauses, generates an answer, and validates it. A separate comparison workflow retrieves evidence for two policies and produces a structured comparison. The graph includes document access and key Azure services; several relationships are omitted because their implementation was not sampled.

Main entry points: [`app/services/advisor_service.py`](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/advisor_service.py) (Question workflow), [`app/api/routes.py`](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/api/routes.py) (HTTP API), [`app/mcp_server.py`](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/mcp_server.py) (MCP tools), [`app/services/comparison_service.py`](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/comparison_service.py) (Plan comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_api["HTTP API<br/>[routes.py]"]
  node_app["Application startup<br/>[main.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
  node_mcp_tools["MCP tools<br/>[mcp_server.py]"]
  node_mcp_setup["MCP server setup<br/>[server.py]"]
end

subgraph group_advisory["Policy advising"]
  node_advisor["Question workflow<br/>[advisor_service.py]"]
  node_classifier["Intent classifier"]
  node_plans["Plan versions<br/>[plan_service.py]"]
  node_guardrails["Safety checks"]
  node_comparison["Plan comparison"]
end

subgraph group_evidence["Policy evidence"]
  node_rag["Clause retrieval and context<br/>[rag_service.py]"]
  node_embeddings["Query embeddings"]
  node_documents["Policy document access"]
  node_blob["Blob storage access<br/>[blob_service.py]"]
end

subgraph group_integrations["External services"]
  node_search_service[("Azure AI Search")]
  node_openai["Azure OpenAI"]
  node_blob_storage[("Azure Blob Storage")]
end

node_user(("Advisor user"))
node_mcp_client(("MCP client"))

node_user -->|"asks question"| node_api
node_app -->|"mounts routes"| node_api
node_api -->|"validates requests"| node_schemas
node_api -->|"processes question"| node_advisor
node_advisor -->|"classifies intent"| node_classifier
node_advisor -->|"resolves version"| node_plans
node_advisor -->|"checks request and answer"| node_guardrails
node_advisor -->|"retrieves context"| node_rag
node_advisor -.->|"generates answer"| node_openai
node_api -->|"compares plans"| node_comparison
node_comparison -->|"retrieves clauses"| node_rag
node_comparison -.->|"generates comparison"| node_openai
node_comparison -->|"validates evidence"| node_guardrails
node_rag -->|"embeds query"| node_embeddings
node_rag -->|"searches clauses"| node_search_service
node_embeddings -.->|"creates embeddings"| node_openai
node_api -->|"lists or fetches PDFs"| node_documents
node_documents -->|"uses storage"| node_blob
node_blob -.->|"reads blobs"| node_blob_storage
node_app -->|"mounts MCP server"| node_mcp_tools
node_mcp_client -.->|"invokes tools"| node_mcp_tools
node_mcp_tools -->|"searches policy"| node_rag
node_mcp_tools -->|"compares policies"| node_comparison
node_mcp_tools -->|"lists documents"| node_documents

click node_api "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/api/routes.py"
click node_app "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/main.py"
click node_schemas "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/schemas.py"
click node_mcp_tools "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/mcp_server.py"
click node_advisor "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/advisor_service.py"
click node_classifier "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/classifier_service.py"
click node_plans "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/plan_service.py"
click node_guardrails "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/guardrail_service.py"
click node_comparison "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/comparison_service.py"
click node_rag "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/rag_service.py"
click node_embeddings "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/embedding_service.py"
click node_documents "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/policy_document_service.py"
click node_blob "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/blob_service.py"
click node_mcp_setup "https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/mcp/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_app,node_schemas,node_mcp_tools,node_mcp_setup,node_user,node_mcp_client toneBlue
class node_advisor,node_classifier,node_plans,node_guardrails,node_comparison toneAmber
class node_rag,node_embeddings,node_documents,node_blob toneMint
class node_search_service,node_openai,node_blob_storage toneRose
```

## Components

### User interfaces

- [HTTP API](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/api/routes.py): `app/api/routes.py`
- [Application startup](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/main.py): `app/main.py`
- [Request schemas](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/schemas.py): `app/schemas.py`
- [MCP tools](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/mcp_server.py): `app/mcp_server.py`
- [MCP server setup](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/mcp/server.py): `mcp/server.py`

### Policy advising

- [Question workflow](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/advisor_service.py): `app/services/advisor_service.py`
- [Intent classifier](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/classifier_service.py): `app/services/classifier_service.py`
- [Plan versions](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/plan_service.py): `app/services/plan_service.py`
- [Safety checks](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/guardrail_service.py): `app/services/guardrail_service.py`
- [Plan comparison](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/comparison_service.py): `app/services/comparison_service.py`

### Policy evidence

- [Clause retrieval and context](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/rag_service.py): `app/services/rag_service.py`
- [Query embeddings](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/embedding_service.py): `app/services/embedding_service.py`
- [Policy document access](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/policy_document_service.py): `app/services/policy_document_service.py`
- [Blob storage access](https://github.com/aasawari-m10/health-insurance-policy-advisor/blob/main/app/services/blob_service.py): `app/services/blob_service.py`

### External services

- **Azure AI Search**
- **Azure OpenAI**
- **Azure Blob Storage**

### Other components

- **Advisor user**
- **MCP client**

## Connections

- Advisor user → HTTP API: asks question (evidence: `app/api/routes.py`)
- Application startup → HTTP API: mounts routes (evidence: `app/main.py`)
- HTTP API → Request schemas: validates requests (evidence: `app/api/routes.py`)
- HTTP API → Question workflow: processes question (evidence: `app/api/routes.py`)
- Question workflow → Intent classifier: classifies intent (evidence: `app/services/advisor_service.py`)
- Question workflow → Plan versions: resolves version (evidence: `app/services/advisor_service.py`)
- Question workflow → Safety checks: checks request and answer (evidence: `app/services/advisor_service.py`)
- Question workflow → Clause retrieval and context: retrieves context (evidence: `app/services/advisor_service.py`)
- Question workflow → Azure OpenAI: generates answer
- HTTP API → Plan comparison: compares plans (evidence: `app/api/routes.py`)
- Plan comparison → Clause retrieval and context: retrieves clauses (evidence: `app/services/comparison_service.py`)
- Plan comparison → Azure OpenAI: generates comparison
- Plan comparison → Safety checks: validates evidence (evidence: `app/services/comparison_service.py`)
- Clause retrieval and context → Query embeddings: embeds query (evidence: `app/services/rag_service.py`)
- Clause retrieval and context → Azure AI Search: searches clauses (evidence: `app/services/rag_service.py`)
- Query embeddings → Azure OpenAI: creates embeddings
- HTTP API → Policy document access: lists or fetches PDFs (evidence: `app/api/routes.py`)
- Policy document access → Blob storage access: uses storage (evidence: `app/services/policy_document_service.py`)
- Blob storage access → Azure Blob Storage: reads blobs
- Application startup → MCP tools: mounts MCP server (evidence: `app/main.py`)
- MCP client → MCP tools: invokes tools
- MCP tools → Clause retrieval and context: searches policy (evidence: `app/mcp_server.py`)
- MCP tools → Plan comparison: compares policies (evidence: `app/mcp_server.py`)
- MCP tools → Policy document access: lists documents (evidence: `app/mcp_server.py`)