# jaiminrakeshshah/insurance-underwritting-agent architecture

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

- Interactive diagram: https://gitdiagram.com/jaiminrakeshshah/insurance-underwritting-agent
- Repository: https://github.com/jaiminrakeshshah/insurance-underwritting-agent

## Overview

A broker submits a medical-insurance application as prose; the pipeline screens it, structures it, supplements it with underwriting context, selects rules, estimates charge, and applies a deterministic gate before any conditional second-opinion route. LLM, scorer, and decision-model adapters are swappable. The graph preserves the documented stages and model providers; unsampled implementation details are represented only where the README or source index supports them.

Main entry points: [`underwriting/pipeline.py`](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/pipeline.py) (Case orchestrator), [`underwriting/adapters/registry.py`](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/adapters/registry.py) (Adapter registry), [`underwriting/blocks/supplement.py`](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/blocks/supplement.py) (Context supplement), [`underwriting/blocks/call.py`](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/blocks/call.py) (LLM call and metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flow["Case workflow"]
  node_pipeline["Case orchestrator<br/>[pipeline.py]"]
  node_pii["PII screen<br/>[PII_Detector.py]"]
  node_injection["Injection screen<br/>[Prompt_Injected.py]"]
  node_structure["Application structuring<br/>[structure.py]"]
  node_retrieval["Rule retrieval prompt<br/>[retrieval.py]"]
  node_rules["Rule selection<br/>[rules.py]"]
  node_risk["Charge scoring<br/>[risk.py]"]
  node_explain["Risk explanation<br/>[explain.py]"]
  node_conclusion["Route proposal<br/>[conclusion.py]"]
  node_gate["Deterministic gate<br/>[gate.py]"]
  node_route["Second-opinion route<br/>[route.py]"]
  node_result["Case recommendation<br/>[pipeline.py]"]
end

subgraph group_models["Model stages"]
  node_llm_call["LLM call and metrics<br/>[call.py]"]
  node_decision_call["Decision-model call<br/>[client.py]"]
end

subgraph group_adapters["Model adapters"]
  node_registry["Adapter registry<br/>[registry.py]"]
  node_llm_adapters["LLM providers"]
  node_scorer["XGBoost scorer<br/>[xgb.py]"]
  node_decision_adapters["Jev, Laya, Kev"]
end

subgraph group_context["Underwriting context"]
  node_supplement["Context supplement<br/>[supplement.py]"]
  node_guidelines["Guidelines and rules<br/>[guidelines.json]"]
  node_bureau["Claims history<br/>[bureau.json]"]
end

node_broker(("Broker"))

node_broker -->|"submits application"| node_pipeline
node_pipeline -->|"runs screen"| node_pii
node_pipeline -->|"runs screen"| node_injection
node_pipeline -->|"structures text"| node_structure
node_pipeline -->|"adds context"| node_supplement
node_supplement -->|"uses guidelines"| node_guidelines
node_supplement -->|"uses history"| node_bureau
node_pipeline -->|"writes retrieval prompt"| node_retrieval
node_pipeline -->|"selects clauses"| node_rules
node_pipeline -->|"scores risk"| node_risk
node_pipeline -->|"explains charge"| node_explain
node_pipeline -->|"proposes route"| node_conclusion
node_pipeline -->|"applies gate"| node_gate
node_pipeline -->|"requests conditional opinion"| node_route
node_pipeline -->|"returns case"| node_result
node_structure -->|"calls model"| node_llm_call
node_retrieval -->|"calls model"| node_llm_call
node_llm_call -->|"completes prompt"| node_llm_adapters
node_rules -->|"asks rule opinion"| node_decision_call
node_route -->|"asks route opinion"| node_decision_call
node_decision_call -->|"posts request"| node_decision_adapters
node_risk -->|"scores intake"| node_scorer
node_registry -->|"resolves provider"| node_llm_adapters
node_registry -->|"resolves provider"| node_scorer
node_registry -->|"resolves provider"| node_decision_adapters

click node_pipeline "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/pipeline.py"
click node_pii "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/PII_Detector.py"
click node_injection "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/Prompt_Injected.py"
click node_structure "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/structure.py"
click node_supplement "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/blocks/supplement.py"
click node_guidelines "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/data/guidelines.json"
click node_bureau "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/data/bureau.json"
click node_retrieval "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/retrieval.py"
click node_rules "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/rules.py"
click node_risk "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/risk.py"
click node_explain "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/explain.py"
click node_conclusion "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/conclusion.py"
click node_gate "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/gate.py"
click node_route "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/route.py"
click node_llm_call "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/blocks/call.py"
click node_decision_call "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/adapters/decision/client.py"
click node_registry "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/adapters/registry.py"
click node_llm_adapters "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/tree/main/underwriting/adapters/llm"
click node_scorer "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/adapters/scorer/xgb.py"
click node_decision_adapters "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/tree/main/underwriting/adapters/decision"
click node_result "https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/pipeline.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_pipeline,node_pii,node_injection,node_structure,node_retrieval,node_rules,node_risk,node_explain,node_conclusion,node_gate,node_route,node_result toneBlue
class node_llm_call,node_decision_call toneAmber
class node_registry,node_llm_adapters,node_scorer,node_decision_adapters toneMint
class node_supplement,node_guidelines,node_bureau toneRose
class node_broker toneIndigo
```

## Components

### Case workflow

- [Case orchestrator](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/pipeline.py): `underwriting/pipeline.py`
- [PII screen](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/PII_Detector.py): `underwriting/stages/PII_Detector.py`
- [Injection screen](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/Prompt_Injected.py): `underwriting/stages/Prompt_Injected.py`
- [Application structuring](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/structure.py): `underwriting/stages/structure.py`
- [Rule retrieval prompt](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/retrieval.py): `underwriting/stages/retrieval.py`
- [Rule selection](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/rules.py): `underwriting/stages/rules.py`
- [Charge scoring](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/risk.py): `underwriting/stages/risk.py`
- [Risk explanation](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/explain.py): `underwriting/stages/explain.py`
- [Route proposal](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/conclusion.py): `underwriting/stages/conclusion.py`
- [Deterministic gate](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/gate.py): `underwriting/stages/gate.py`
- [Second-opinion route](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/stages/route.py): `underwriting/stages/route.py`
- [Case recommendation](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/pipeline.py): `underwriting/pipeline.py`

### Model stages

- [LLM call and metrics](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/blocks/call.py): `underwriting/blocks/call.py`
- [Decision-model call](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/adapters/decision/client.py): `underwriting/adapters/decision/client.py`

### Model adapters

- [Adapter registry](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/adapters/registry.py): `underwriting/adapters/registry.py`
- [LLM providers](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/tree/main/underwriting/adapters/llm): `underwriting/adapters/llm`
- [XGBoost scorer](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/adapters/scorer/xgb.py): `underwriting/adapters/scorer/xgb.py`
- [Jev, Laya, Kev](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/tree/main/underwriting/adapters/decision): `underwriting/adapters/decision`

### Underwriting context

- [Context supplement](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/blocks/supplement.py): `underwriting/blocks/supplement.py`
- [Guidelines and rules](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/data/guidelines.json): `underwriting/data/guidelines.json`
- [Claims history](https://github.com/jaiminrakeshshah/insurance-underwritting-agent/blob/main/underwriting/data/bureau.json): `underwriting/data/bureau.json`

### Other components

- **Broker**

## Connections

- Broker → Case orchestrator: submits application (evidence: `README.md`)
- Case orchestrator → PII screen: runs screen (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Injection screen: runs screen (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Application structuring: structures text (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Context supplement: adds context (evidence: `underwriting/pipeline.py`)
- Context supplement → Guidelines and rules: uses guidelines (evidence: `README.md`)
- Context supplement → Claims history: uses history (evidence: `README.md`)
- Case orchestrator → Rule retrieval prompt: writes retrieval prompt (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Rule selection: selects clauses (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Charge scoring: scores risk (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Risk explanation: explains charge (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Route proposal: proposes route (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Deterministic gate: applies gate (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Second-opinion route: requests conditional opinion (evidence: `underwriting/pipeline.py`)
- Case orchestrator → Case recommendation: returns case (evidence: `underwriting/pipeline.py`)
- Application structuring → LLM call and metrics: calls model (evidence: `underwriting/stages/structure.py`)
- Rule retrieval prompt → LLM call and metrics: calls model (evidence: `underwriting/stages/retrieval.py`)
- LLM call and metrics → LLM providers: completes prompt (evidence: `underwriting/blocks/call.py`)
- Rule selection → Decision-model call: asks rule opinion (evidence: `underwriting/stages/rules.py`)
- Second-opinion route → Decision-model call: asks route opinion (evidence: `underwriting/stages/route.py`)
- Decision-model call → Jev, Laya, Kev: posts request (evidence: `underwriting/adapters/decision/client.py`)
- Charge scoring → XGBoost scorer: scores intake (evidence: `underwriting/stages/risk.py`)
- Adapter registry → LLM providers: resolves provider (evidence: `underwriting/adapters/registry.py`)
- Adapter registry → XGBoost scorer: resolves provider (evidence: `underwriting/adapters/registry.py`)
- Adapter registry → Jev, Laya, Kev: resolves provider (evidence: `underwriting/adapters/registry.py`)
