# yangzhangscut2025/ai-insurance architecture

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

- Interactive diagram: https://gitdiagram.com/yangzhangscut2025/ai-insurance
- Repository: https://github.com/yangzhangscut2025/ai-insurance

## Overview

AI 未来保险 is a Flask insurance assistant with three main user journeys: personalized insurance Q&A (including uploaded-plan summarization), role-play sales practice with optional speech, and document-grounded RAG answers. Account, profile, role, and conversation data support those journeys; invitation email and onboarding UI are additional capabilities. The map follows documented features and sampled route/service calls; several subsystems are represented at their documented source paths because their implementation was not sampled.

Main entry points: [`app/main/views.py`](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py) (Assistant routes), [`app/main/rag.py`](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/rag.py) (Hybrid RAG engine), [`app/models.py`](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/models.py) (User and chat records), [`app/templates`](https://github.com/yangzhangscut2025/ai-insurance/tree/main/app/templates) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and accounts"]
  node_app["Flask application<br/>[__init__.py]"]
  node_auth["Authentication<br/>[views.py]"]
  node_pages["Chat interface"]
  node_main_routes["Assistant routes<br/>[views.py]"]
  node_forms["Input forms<br/>[forms.py]"]
  node_email["Invitation mailer<br/>[send.py]"]
end

subgraph group_insurance["Insurance assistant"]
  node_profile["Profile capture<br/>[views.py]"]
  node_insurance_agent["Insurance agent<br/>[agent.py]"]
  node_plan_upload["Plan upload and summary<br/>[views.py]"]
end

subgraph group_practice["Sales practice"]
  node_role_setup["Custom role setup<br/>[views.py]"]
  node_role_agent["Role-play agent<br/>[agent.py]"]
  node_speech["Speech synthesis<br/>[audio.py]"]
end

subgraph group_knowledge["Knowledge and state"]
  node_rag_api["RAG routes<br/>[views.py]"]
  node_rag_engine["Hybrid RAG engine<br/>[rag.py]"]
  node_documents["Insurance documents"]
  node_embeddings["BGE embeddings<br/>[rag.py]"]
  node_vectors[("ChromaDB index")]
  node_records[("User and chat records<br/>[models.py]")]
end

node_visitor(("User"))
node_qwen["Qwen / DashScope"]
node_tts_service["DashScope TTS"]
node_smtp["SMTP service"]

node_visitor -->|"uses"| node_pages
node_pages -->|"signs in"| node_auth
node_auth -->|"reads users"| node_records
node_app -->|"registers routes"| node_main_routes
node_app -->|"registers routes"| node_auth
node_pages -->|"submits requests"| node_main_routes
node_main_routes -->|"validates input"| node_forms
node_main_routes -->|"saves profile"| node_profile
node_profile -->|"writes profile"| node_records
node_main_routes -->|"stores answers"| node_records
node_main_routes -->|"queries"| node_insurance_agent
node_insurance_agent -->|"runs assistant"| node_qwen
node_main_routes -->|"handles upload"| node_plan_upload
node_plan_upload -->|"summarizes plan"| node_qwen
node_main_routes -->|"creates role"| node_role_setup
node_role_setup -->|"writes role"| node_records
node_main_routes -->|"sends dialogue"| node_role_agent
node_role_agent -->|"runs assistant"| node_qwen
node_main_routes -->|"requests speech"| node_speech
node_speech -->|"synthesizes audio"| node_tts_service
node_main_routes -->|"serves RAG actions"| node_rag_api
node_rag_api -->|"queries or rebuilds"| node_rag_engine
node_rag_engine -->|"loads documents"| node_documents
node_rag_engine -->|"embeds chunks"| node_embeddings
node_rag_engine -->|"indexes and searches"| node_vectors
node_rag_engine -->|"generates answer"| node_qwen
node_main_routes -->|"sends invitation"| node_email
node_email -->|"sends mail"| node_smtp

click node_app "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/__init__.py"
click node_auth "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/auth/views.py"
click node_pages "https://github.com/yangzhangscut2025/ai-insurance/tree/main/app/templates"
click node_main_routes "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py"
click node_forms "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/forms.py"
click node_profile "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py"
click node_insurance_agent "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/agent.py"
click node_plan_upload "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py"
click node_role_setup "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py"
click node_role_agent "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/agent.py"
click node_speech "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/audio.py"
click node_rag_api "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py"
click node_rag_engine "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/rag.py"
click node_embeddings "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/rag.py"
click node_records "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/models.py"
click node_email "https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/send.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,node_auth,node_pages,node_main_routes,node_forms,node_email,node_visitor toneBlue
class node_profile,node_insurance_agent,node_plan_upload toneAmber
class node_role_setup,node_role_agent,node_speech toneMint
class node_rag_api,node_rag_engine,node_documents,node_embeddings,node_vectors,node_records toneRose
class node_qwen,node_tts_service,node_smtp toneIndigo
```

## Components

### Web and accounts

- [Flask application](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/__init__.py): `app/__init__.py`
- [Authentication](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/auth/views.py): `app/auth/views.py`
- [Chat interface](https://github.com/yangzhangscut2025/ai-insurance/tree/main/app/templates): `app/templates`
- [Assistant routes](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py): `app/main/views.py`
- [Input forms](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/forms.py): `app/main/forms.py`
- [Invitation mailer](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/send.py): `app/main/send.py`

### Insurance assistant

- [Profile capture](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py): `app/main/views.py`
- [Insurance agent](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/agent.py): `app/main/agent.py`
- [Plan upload and summary](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py): `app/main/views.py`

### Sales practice

- [Custom role setup](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py): `app/main/views.py`
- [Role-play agent](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/agent.py): `app/main/agent.py`
- [Speech synthesis](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/audio.py): `app/main/audio.py`

### Knowledge and state

- [RAG routes](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/views.py): `app/main/views.py`
- [Hybrid RAG engine](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/rag.py): `app/main/rag.py`
- **Insurance documents**
- [BGE embeddings](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/main/rag.py): `app/main/rag.py`
- **ChromaDB index**
- [User and chat records](https://github.com/yangzhangscut2025/ai-insurance/blob/main/app/models.py): `app/models.py`

### Other components

- **User**
- **Qwen / DashScope**
- **DashScope TTS**
- **SMTP service**

## Connections

- User → Chat interface: uses
- Chat interface → Authentication: signs in
- Authentication → User and chat records: reads users
- Flask application → Assistant routes: registers routes
- Flask application → Authentication: registers routes
- Chat interface → Assistant routes: submits requests
- Assistant routes → Input forms: validates input
- Assistant routes → Profile capture: saves profile
- Profile capture → User and chat records: writes profile
- Assistant routes → User and chat records: stores answers
- Assistant routes → Insurance agent: queries
- Insurance agent → Qwen / DashScope: runs assistant
- Assistant routes → Plan upload and summary: handles upload
- Plan upload and summary → Qwen / DashScope: summarizes plan
- Assistant routes → Custom role setup: creates role
- Custom role setup → User and chat records: writes role
- Assistant routes → Role-play agent: sends dialogue
- Role-play agent → Qwen / DashScope: runs assistant
- Assistant routes → Speech synthesis: requests speech
- Speech synthesis → DashScope TTS: synthesizes audio
- Assistant routes → RAG routes: serves RAG actions
- RAG routes → Hybrid RAG engine: queries or rebuilds
- Hybrid RAG engine → Insurance documents: loads documents
- Hybrid RAG engine → BGE embeddings: embeds chunks
- Hybrid RAG engine → ChromaDB index: indexes and searches
- Hybrid RAG engine → Qwen / DashScope: generates answer
- Assistant routes → Invitation mailer: sends invitation
- Invitation mailer → SMTP service: sends mail