# jaspinxu/insuretutor architecture

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

- Interactive diagram: https://gitdiagram.com/jaspinxu/insuretutor
- Repository: https://github.com/jaspinxu/insuretutor

## Overview

InsureTutor is a bilingual tutor for insurance-plan documents. A user submits a question in the React app; the backend streams a turn through input checks, intent routing, hybrid retrieval, grounded generation (or offline extracts), and answer validation. Citations lead to source passages and PDF pages, while conversations persist for history and follow-ups. The graph includes the documented ingestion and retrieval capabilities. Some subsystem links rely on README descriptions or SOURCE INDEX references; unsampled internals are not expanded.

Main entry points: [`backend/app/chat.py`](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/chat.py) (Turn orchestrator), [`backend/app/llm/base.py`](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/base.py) (LLM interface), [`frontend/src/App.tsx`](https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/App.tsx) (Chat app), [`backend/app/rag/retriever.py`](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/rag/retriever.py) (Hybrid retriever)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat interface"]
  node_app_ui["Chat app<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_message_view["Answer view<br/>[MessageView.tsx]"]
  node_source_panel["Source panel<br/>[SourcePanel.tsx]"]
  node_localization["Localization<br/>[i18n.ts]"]
end

subgraph group_service["Chat service"]
  node_chat["Turn orchestrator<br/>[chat.py]"]
  node_prompting["Grounded prompts<br/>[prompts.py]"]
end

subgraph group_knowledge["Document knowledge"]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
  node_bm25["Keyword search<br/>[bm25.py]"]
  node_embeddings["Dense embeddings<br/>[embeddings.py]"]
  node_ingestion["PDF ingestion<br/>[pipeline.py]"]
end

subgraph group_safety["Safety and language"]
  node_input_guard["Input guard<br/>[input.py]"]
  node_router["Intent router<br/>[router.py]"]
  node_output_guard["Answer checks<br/>[output.py]"]
  node_fact_check["Citation fact check<br/>[verify.py]"]
  node_language["Language handling<br/>[lang.py]"]
end

subgraph group_runtime["Runtime services"]
  node_api_routes["HTTP API<br/>[routes.py]"]
  node_store[("Conversation store<br/>[store.py]")]
  node_llm_factory["Provider selection<br/>[__init__.py]"]
  node_llm_interface["LLM interface<br/>[base.py]"]
  node_openai["OpenAI provider<br/>[openai_provider.py]"]
  node_anthropic["Anthropic provider"]
end

node_user(("Plan reader"))
node_model_service["LLM service"]
node_pdf_reader["PDF reader"]

node_user -->|"asks question"| node_app_ui
node_app_ui -->|"starts chat"| node_api_client
node_app_ui -->|"renders answers"| node_message_view
node_message_view -->|"opens citations"| node_source_panel
node_app_ui -->|"localizes interface"| node_localization
node_api_client -->|"sends chat request"| node_api_routes
node_api_routes -->|"dispatches turns"| node_chat
node_api_routes -->|"serves history"| node_store
node_chat -->|"checks input"| node_input_guard
node_chat -->|"routes intent"| node_router
node_chat -->|"searches sources"| node_retriever
node_chat -->|"builds grounded prompt"| node_prompting
node_chat -->|"checks answer"| node_output_guard
node_chat -->|"verifies claims"| node_fact_check
node_chat -->|"detects answer language"| node_language
node_chat -->|"reads and saves turns"| node_store
node_retriever -->|"runs keyword search"| node_bm25
node_retriever -->|"uses dense vectors"| node_embeddings
node_retriever -->|"loads corpus"| node_ingestion
node_ingestion -->|"extracts document pages"| node_pdf_reader
node_router -->|"requests structured route"| node_llm_interface
node_chat -->|"streams answer"| node_llm_interface
node_llm_factory -->|"selects provider"| node_openai
node_llm_factory -->|"selects provider"| node_anthropic
node_openai -->|"implements interface"| node_llm_interface
node_anthropic -->|"implements interface"| node_llm_interface
node_llm_interface -.->|"calls configured model"| node_model_service

click node_app_ui "https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/api.ts"
click node_message_view "https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/components/MessageView.tsx"
click node_source_panel "https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/components/SourcePanel.tsx"
click node_localization "https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/i18n.ts"
click node_api_routes "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/api/routes.py"
click node_chat "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/chat.py"
click node_input_guard "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/guardrails/input.py"
click node_router "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/guardrails/router.py"
click node_retriever "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/rag/retriever.py"
click node_bm25 "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/rag/bm25.py"
click node_embeddings "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/rag/embeddings.py"
click node_ingestion "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/ingest/pipeline.py"
click node_prompting "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/prompts.py"
click node_output_guard "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/guardrails/output.py"
click node_fact_check "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/guardrails/verify.py"
click node_language "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/lang.py"
click node_store "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/store.py"
click node_llm_factory "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/__init__.py"
click node_llm_interface "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/base.py"
click node_openai "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/openai_provider.py"
click node_anthropic "https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/anthropic_provider.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_app_ui,node_api_client,node_message_view,node_source_panel,node_localization toneBlue
class node_chat,node_prompting toneAmber
class node_retriever,node_bm25,node_embeddings,node_ingestion toneMint
class node_input_guard,node_router,node_output_guard,node_fact_check,node_language toneRose
class node_api_routes,node_store,node_llm_factory,node_llm_interface,node_openai,node_anthropic,node_user,node_model_service,node_pdf_reader toneIndigo
```

## Components

### Chat interface

- [Chat app](https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Answer view](https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/components/MessageView.tsx): `frontend/src/components/MessageView.tsx`
- [Source panel](https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/components/SourcePanel.tsx): `frontend/src/components/SourcePanel.tsx`
- [Localization](https://github.com/jaspinxu/insuretutor/blob/main/frontend/src/i18n.ts): `frontend/src/i18n.ts`

### Chat service

- [Turn orchestrator](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/chat.py): `backend/app/chat.py`
- [Grounded prompts](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/prompts.py): `backend/app/prompts.py`

### Document knowledge

- [Hybrid retriever](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Keyword search](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/rag/bm25.py): `backend/app/rag/bm25.py`
- [Dense embeddings](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/rag/embeddings.py): `backend/app/rag/embeddings.py`
- [PDF ingestion](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/ingest/pipeline.py): `backend/app/ingest/pipeline.py`

### Safety and language

- [Input guard](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/guardrails/input.py): `backend/app/guardrails/input.py`
- [Intent router](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/guardrails/router.py): `backend/app/guardrails/router.py`
- [Answer checks](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/guardrails/output.py): `backend/app/guardrails/output.py`
- [Citation fact check](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/guardrails/verify.py): `backend/app/guardrails/verify.py`
- [Language handling](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/lang.py): `backend/app/lang.py`

### Runtime services

- [HTTP API](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Conversation store](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/store.py): `backend/app/store.py`
- [Provider selection](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/__init__.py): `backend/app/llm/__init__.py`
- [LLM interface](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/base.py): `backend/app/llm/base.py`
- [OpenAI provider](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/openai_provider.py): `backend/app/llm/openai_provider.py`
- [Anthropic provider](https://github.com/jaspinxu/insuretutor/blob/main/backend/app/llm/anthropic_provider.py): `backend/app/llm/anthropic_provider.py`

### Other components

- **Plan reader**
- **LLM service**
- **PDF reader**

## Connections

- Plan reader → Chat app: asks question (evidence: `README.md`)
- Chat app → API client: starts chat (evidence: `frontend/src/App.tsx`)
- Chat app → Answer view: renders answers (evidence: `frontend/src/App.tsx`)
- Answer view → Source panel: opens citations (evidence: `README.md`)
- Chat app → Localization: localizes interface (evidence: `frontend/src/App.tsx`)
- API client → HTTP API: sends chat request (evidence: `README.md`)
- HTTP API → Turn orchestrator: dispatches turns (evidence: `backend/app/api/routes.py`)
- HTTP API → Conversation store: serves history (evidence: `backend/app/api/routes.py`)
- Turn orchestrator → Input guard: checks input (evidence: `backend/app/chat.py`)
- Turn orchestrator → Intent router: routes intent (evidence: `backend/app/chat.py`)
- Turn orchestrator → Hybrid retriever: searches sources (evidence: `backend/app/chat.py`)
- Turn orchestrator → Grounded prompts: builds grounded prompt (evidence: `backend/app/chat.py`)
- Turn orchestrator → Answer checks: checks answer (evidence: `backend/app/chat.py`)
- Turn orchestrator → Citation fact check: verifies claims (evidence: `backend/app/chat.py`)
- Turn orchestrator → Language handling: detects answer language (evidence: `backend/app/chat.py`)
- Turn orchestrator → Conversation store: reads and saves turns (evidence: `backend/app/chat.py`)
- Hybrid retriever → Keyword search: runs keyword search (evidence: `backend/app/rag/retriever.py`)
- Hybrid retriever → Dense embeddings: uses dense vectors (evidence: `backend/app/rag/retriever.py`)
- Hybrid retriever → PDF ingestion: loads corpus (evidence: `backend/app/rag/retriever.py`)
- PDF ingestion → PDF reader: extracts document pages (evidence: `backend/app/ingest/pipeline.py`)
- Intent router → LLM interface: requests structured route (evidence: `backend/app/guardrails/router.py`)
- Turn orchestrator → LLM interface: streams answer (evidence: `backend/app/chat.py`)
- Provider selection → OpenAI provider: selects provider (evidence: `backend/app/llm/__init__.py`)
- Provider selection → Anthropic provider: selects provider (evidence: `backend/app/llm/__init__.py`)
- OpenAI provider → LLM interface: implements interface (evidence: `backend/app/llm/openai_provider.py`)
- Anthropic provider → LLM interface: implements interface (evidence: `backend/app/llm/anthropic_provider.py`)
- LLM interface → LLM service: calls configured model
