# unidentified-user4321/claimwise architecture

> Architecture diagram of the GitHub repository unidentified-user4321/claimwise, 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/unidentified-user4321/claimwise
- Repository: https://github.com/unidentified-user4321/claimwise

## Overview

This product assists insurance customers and claim employees through claim submission, automated assessment, and human disposition. The documented assessment stages combine fraud scoring, description classification, deterministic policy checks, retrieved policy evidence, and similar-claim detection; reviewers then record actions and investigation history. The React client talks to FastAPI, whose services coordinate assessment and persistence. The README documents several capabilities whose internal wiring was not sampled, so those links are shown only where the documented workflow supports them. External provider and database links reflect the described integrations.

Main entry points: [`backend/app/services/analysis.py`](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/analysis.py) (Assessment orchestration), [`frontend/src/App.tsx`](https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/App.tsx) (Role-based app), [`backend/app/db/database.py`](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/db/database.py) (PostgreSQL), [`frontend/src/services/api.ts`](https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_webapp["Role-based app<br/>[App.tsx]"]
  node_clientclaims["Client claims<br/>[SubmitClaim.tsx]"]
  node_employeereview["Employee review"]
  node_historyview["Investigation history"]
  node_session["Session mapping<br/>[session.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_authroutes["Auth routes<br/>[auth.py]"]
  node_claimroutes["Claim routes<br/>[claims.py]"]
  node_analysisroutes["Analysis routes<br/>[analysis.py]"]
end

subgraph group_assessment["Claim assessment"]
  node_analysis_service["Assessment orchestration<br/>[analysis.py]"]
  node_fraudmodel["Fraud prediction<br/>[ml.py]"]
  node_nlpmodel["Description classification<br/>[ml.py]"]
  node_similarity["Similar claims"]
end

subgraph group_policy["Policy intelligence"]
  node_policychecks["Deterministic checks<br/>[policy_checks.py]"]
  node_policy_rag["Policy analysis<br/>[policy_rag.py]"]
  node_retriever["Policy retrieval<br/>[retriever.py]"]
  node_pinecone[("Pinecone vectors<br/>[pinecone_store.py]")]
end

subgraph group_records["Claim records"]
  node_review["Review actions<br/>[claim_review.py]"]
  node_status["Status transitions<br/>[claim_status.py]"]
  node_context["Claim context<br/>[claim_context.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_models["Domain records<br/>[models.py]"]
end

node_client(("Client"))
node_employee(("Claims employee"))
node_clerk{{"Clerk"}}
node_gemini{{"Gemini"}}

node_client -->|"uses"| node_webapp
node_employee -->|"uses"| node_webapp
node_webapp -->|"routes clients"| node_clientclaims
node_webapp -->|"routes employees"| node_employeereview
node_webapp -->|"routes history"| node_historyview
node_webapp -->|"checks session"| node_session
node_session -->|"authenticates with"| node_clerk
node_session -->|"resolves identity"| node_api_client
node_clientclaims -->|"submits claims"| node_api_client
node_employeereview -->|"records decisions"| node_api_client
node_historyview -->|"requests history"| node_api_client
node_api_client -->|"sends requests"| node_fastapi
node_fastapi -->|"dispatches auth"| node_authroutes
node_fastapi -->|"dispatches claims"| node_claimroutes
node_fastapi -->|"dispatches analysis"| node_analysisroutes
node_authroutes -->|"reads and writes"| node_database
node_claimroutes -->|"reads and writes"| node_database
node_analysisroutes -->|"invokes assessment"| node_analysis_service
node_analysis_service -->|"builds claim context"| node_context
node_analysis_service -->|"scores fraud risk"| node_fraudmodel
node_analysis_service -->|"classifies description"| node_nlpmodel
node_analysis_service -->|"checks policy rules"| node_policychecks
node_analysis_service -->|"analyzes policy"| node_policy_rag
node_analysis_service -->|"finds similar claims"| node_similarity
node_analysis_service -->|"persists analysis"| node_database
node_policy_rag -->|"requests evidence"| node_retriever
node_retriever -->|"searches vectors"| node_pinecone
node_policy_rag -.->|"generates analysis"| node_gemini
node_claimroutes -->|"records review action"| node_review
node_review -->|"validates transition"| node_status
node_review -->|"writes review history"| node_database
node_claimroutes -->|"reads investigation history"| node_database
node_database -->|"maps records"| node_models

click node_webapp "https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/App.tsx"
click node_clientclaims "https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/pages/SubmitClaim.tsx"
click node_employeereview "https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/pages/EmployeeClaimDetails.tsx"
click node_historyview "https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/pages/InvestigationHistory.tsx"
click node_session "https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/services/session.tsx"
click node_api_client "https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/services/api.ts"
click node_fastapi "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/main.py"
click node_authroutes "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/api/auth.py"
click node_claimroutes "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/api/claims.py"
click node_analysisroutes "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/api/analysis.py"
click node_analysis_service "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/analysis.py"
click node_fraudmodel "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/ml.py"
click node_nlpmodel "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/ml.py"
click node_similarity "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/claim_similarity.py"
click node_policychecks "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/policy_checks.py"
click node_policy_rag "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/rag/policy_rag.py"
click node_retriever "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/rag/retriever.py"
click node_pinecone "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/rag/pinecone_store.py"
click node_review "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/claim_review.py"
click node_status "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/claim_status.py"
click node_context "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/claim_context.py"
click node_database "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/db/database.py"
click node_models "https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/db/models.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_webapp,node_clientclaims,node_employeereview,node_historyview,node_session,node_api_client,node_client toneBlue
class node_fastapi,node_authroutes,node_claimroutes,node_analysisroutes toneAmber
class node_analysis_service,node_fraudmodel,node_nlpmodel,node_similarity toneMint
class node_policychecks,node_policy_rag,node_retriever,node_pinecone toneRose
class node_review,node_status,node_context,node_database,node_models,node_employee,node_clerk,node_gemini toneIndigo
```

## Components

### User experience

- [Role-based app](https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Client claims](https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/pages/SubmitClaim.tsx): `frontend/src/pages/SubmitClaim.tsx`
- [Employee review](https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/pages/EmployeeClaimDetails.tsx): `frontend/src/pages/EmployeeClaimDetails.tsx`
- [Investigation history](https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/pages/InvestigationHistory.tsx): `frontend/src/pages/InvestigationHistory.tsx`
- [Session mapping](https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/services/session.tsx): `frontend/src/services/session.tsx`
- [API client](https://github.com/unidentified-user4321/claimwise/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API and identity

- [FastAPI app](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Claim routes](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/api/claims.py): `backend/app/api/claims.py`
- [Analysis routes](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/api/analysis.py): `backend/app/api/analysis.py`

### Claim assessment

- [Assessment orchestration](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/analysis.py): `backend/app/services/analysis.py`
- [Fraud prediction](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/ml.py): `backend/app/ml.py`
- [Description classification](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/ml.py): `backend/app/ml.py`
- [Similar claims](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/claim_similarity.py): `backend/app/services/claim_similarity.py`

### Policy intelligence

- [Deterministic checks](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/policy_checks.py): `backend/app/policy_checks.py`
- [Policy analysis](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/rag/policy_rag.py): `backend/app/rag/policy_rag.py`
- [Policy retrieval](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Pinecone vectors](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/rag/pinecone_store.py): `backend/app/rag/pinecone_store.py`

### Claim records

- [Review actions](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/claim_review.py): `backend/app/services/claim_review.py`
- [Status transitions](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/claim_status.py): `backend/app/services/claim_status.py`
- [Claim context](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/services/claim_context.py): `backend/app/services/claim_context.py`
- [PostgreSQL](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Domain records](https://github.com/unidentified-user4321/claimwise/blob/main/backend/app/db/models.py): `backend/app/db/models.py`

### Other components

- **Client**
- **Claims employee**
- **Clerk**
- **Gemini**

## Connections

- Client → Role-based app: uses
- Claims employee → Role-based app: uses
- Role-based app → Client claims: routes clients
- Role-based app → Employee review: routes employees
- Role-based app → Investigation history: routes history
- Role-based app → Session mapping: checks session
- Session mapping → Clerk: authenticates with
- Session mapping → API client: resolves identity
- Client claims → API client: submits claims
- Employee review → API client: records decisions
- Investigation history → API client: requests history
- API client → FastAPI app: sends requests
- FastAPI app → Auth routes: dispatches auth
- FastAPI app → Claim routes: dispatches claims
- FastAPI app → Analysis routes: dispatches analysis
- Auth routes → PostgreSQL: reads and writes
- Claim routes → PostgreSQL: reads and writes
- Analysis routes → Assessment orchestration: invokes assessment
- Assessment orchestration → Claim context: builds claim context
- Assessment orchestration → Fraud prediction: scores fraud risk
- Assessment orchestration → Description classification: classifies description
- Assessment orchestration → Deterministic checks: checks policy rules
- Assessment orchestration → Policy analysis: analyzes policy
- Assessment orchestration → Similar claims: finds similar claims
- Assessment orchestration → PostgreSQL: persists analysis
- Policy analysis → Policy retrieval: requests evidence
- Policy retrieval → Pinecone vectors: searches vectors
- Policy analysis → Gemini: generates analysis
- Claim routes → Review actions: records review action
- Review actions → Status transitions: validates transition
- Review actions → PostgreSQL: writes review history
- Claim routes → PostgreSQL: reads investigation history
- PostgreSQL → Domain records: maps records